def test_add_indent(self):
input = ["This is the first line", "", " This is the third line"]
expected = [
" This is the first line", "", " This is the third line"]
output = add_indent(input, indent=3)
self.assertEqual(output, expected)
expected = [
"This is the first line", "", " This is the third line"]
output = add_indent(input, indent=0)
self.assertEqual(output, expected)
expected = [
" This is the first line", "", " This is the third line"]
output = add_indent(input)
self.assertEqual(output, expected)
def to_rst(self):
""" Render an item as an argument using the ``:param:``
role.
Example
-------
::
>>> item = Item('indent', 'int',
... ['The indent to use for the description block.',
''
'This is the second paragraph of the argument definition.'])
>>> renderer = Argument(item)
>>> renderer.to_rst()
:param indent:
The indent to use for the description block.
This is the second paragraph of the argument definition.
:type indent: int
.. note::
There is no new line added at the last line of the :meth:`to_rst`
method.
"""
item = self.item
argument = fix_star(item.term)
argument = fix_trailing_underscore(argument)
argument_types = ' or '.join(item.classifiers)
definition = '\n'.join(add_indent(item.definition))
template = self.templates[item.mode].format(
argument, argument_types, definition)
return template.splitlines()
def item_list(doc, header, renderer=ListItem, item_class=OrDefinitionItem):
""" Render the section to sphinx friendly item list.
Arguments
---------
doc : DocRender
The docstring container.
header : str
The header name that is used for the fields (i.e. ``:<header>:``).
renderer : Renderer
A renderer instance to render the items.
item_class : type
The item parser class to use. Default is :class:`~.OrDefinitionItem`.
"""
items = doc.extract_items(item_class)
lines = [':{0}:'.format(header.lower())]
prefix = None if len(items) == 1 else '-'
renderer = renderer()
for item in items:
renderer.item = item
lines += add_indent(renderer.to_rst(prefix))
lines.append('')
return lines
def returns_section(doc, header, renderer=None, item_class=None):
""" A return item list section that also accepts a paragraph as
a description.
"""
lines = item_list(doc, header, renderer, item_class)
if len(lines) == 1:
paragraph = doc.get_next_paragraph()
lines += add_indent(paragraph)
return lines
def example_paragraph(doc, header, renderer=None, item_class=None):
""" Render the example section to use the ``::`` directive.
The section is expected to be given as a paragraph.
"""
paragraph = doc.get_next_paragraph()
lines = ['**{0}**'.format(header), '::', '']
lines += add_indent(paragraph)
return lines
def returns_section(doc, header, renderer=None, item_class=None):
""" A return item list section that also accepts a paragraph as
a description.
"""
lines = item_list(doc, header, renderer, item_class)
if len(lines) == 1:
paragraph = doc.get_next_paragraph()
lines += add_indent(paragraph)
return lines
def example_paragraph(doc, header, renderer=None, item_class=None):
""" Render the example section to use the ``::`` directive.
The section is expected to be given as a paragraph.
"""
paragraph = doc.get_next_paragraph()
lines = ['**{0}**'.format(header), '::', '']
lines += add_indent(paragraph)
return lines
def notes_paragraph(doc, header, renderer=None, item_class=None):
"""Render the note section to use the rst ``.. note`` directive.
The section is expected to be given as a paragraph.
"""
paragraph = doc.get_next_paragraph()
lines = ['.. note::']
lines += add_indent(paragraph)
return lines
def to_rst(self, **kwards):
""" Outputs the Item in sphinx friendly rst.
The method renders the `definition` into a list of lines that
follow the rst markup of a sphinx definition item::
<term>
(<classifier(s)>) --
<definition>
Returns
-------
lines : list
A list of string lines rendered in rst.
Example
-------
::
>>> item = Item(
'lines', 'list',
['A list of string lines rendered in rst.'])
>>> renderer = Definition(item)
>>> renderer.to_rst
lines
*(list)* --
A list of string lines rendered in rst.
.. note:: An empty line is added at the end of the list of strings so
that the results can be concatenated directly and rendered properly
by sphinx.
"""
item = self.item
postfix = ' --' if (len(item.definition) > 0) else ''
lines = []
lines += [item.term]
lines += [NEW_LINE]
number_of_classifiers = len(item.classifiers)
if number_of_classifiers == 1:
lines += [' *({0[0]})*{1}'.format(item.classifiers, postfix)]
elif number_of_classifiers == 2:
lines += [
' *({0[0]} or {0[1]})*{2}'.format(
item.classifiers, postfix)]
lines += add_indent(item.definition) # definition is already a list
lines += [NEW_LINE]
return lines
def to_rst(self, prefix=None):
""" Renders an item as items in an rst list.
Arguments
---------
prefix : str
The prefix to use. For example if the item is part of an
unnumbered list then ``prefix='-'``.
Example
-------
>>> item = Item('indent', 'int',
... ['The indent to use for the description block.'])
>>> renderer = ListItem(item)
>>> renderer.to_rst(prefix='-')
- **indent** (`int`) --
The indent to use for the description block.
>>> item = Item('indent', 'int',
... ['The indent to use for'
'the description block.'])
>>> renderer = ListItem(item)
>>> renderer.to_rst(prefix='-')
- **indent** (`int`) --
The indent to use for
the description block.
.. note:: An empty line is added at the end of the list of strings so
that the results can be concatenated directly and rendered properly
by sphinx.
"""
item = self.item
indent = 0 if (prefix is None) else len(prefix) + 1
definition = '\n'.join(add_indent(item.definition, indent))
template = self.templates[item.mode].format(
item.term, ' or '.join(item.classifiers), definition)
if prefix is not None:
template = prefix + ' ' + template
return template.splitlines()
def to_rst(self):
""" Return the attribute info using the attribute sphinx markup.
Examples
--------
::
>>> item = Item('indent', 'int',
... ['The indent to use for the description block.'])
>>> Attribute(item).to_rst()
.. attribute:: indent
:annotation: = `int`
The indent to use for the description block
>>>
::
>>> item = Item('indent', '',
... ['The indent to use for the description block.'])
>>> Attribute(item).to_rst()
.. attribute:: indent
The indent to use for the description block
>>>
.. note:: An empty line is added at the end of the list of strings so
that the results can be concatenated directly and rendered properly
by sphinx.
"""
item = self.item
definition = '\n'.join(add_indent(item.definition))
template = self.templates[item.mode].format(
item.term, ' or '.join(item.classifiers), definition)
return template.splitlines()
