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 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()