Library Reference¶
The extension is separated into three main parts.
Styles¶
-
class
sectiondoc.styles.
DocRender
(lines, sections=None)[source]¶ Docstring rendering class.
The class’ main purpose is to parse the docstring and find the sections that need to be refactored. The operation take place in two stages:
- The class is instanciated with the appropriate section renderers
- The
parse
method is called to parse and render the sections inplace.
-
docstring
= list¶ A list of strings (lines) that holds docstrings. The lines are changed inplace.
-
index
= int¶ The zero-based line number of the docstring that is currently processed.
-
sections
= dict¶ The sections that will be detected and rendered. The dictionary maps the section headers for detection to a tuple containing the section rendering function and optional values for the item renderer and parser.
Parameters: - lines (list) – The docstring as a list of strings where to render the sections
- sections (dict) – The sections that will be detected and rendered. The dictionary maps the section headers for detection to a tuple containing the section rendering function and optional values for the item renderer and parser. If on section rendering information is provided the default behaviour of the class is to render every section using the rubric rendering function.
-
extract_items
(item_type=None)[source]¶ Extract the section items from a docstring.
Parse the items in the description of a section into items of the provided item type. The method starts at the current line index position and checks if in the next two lines contain a valid item of the desired type. If successful, the lines that belong to the item description block (i.e. item header + item body) are popped out from the docstring and passed to the
item_type.parser
class method to get a new instance ofitem_type
.The process is repeated until there are no compatible
item_type
items found in the section or we run out of docstring lines, The collected item instances are returnedThe exit conditions allow for two valid section item layouts:
No lines between items:
<header1> <description1> <more description> <header2> <description2>
One line between items:
<header1> <description1> <more description> <header2> <description2>
Parameters: item_type (Item) – An Item type or a subclass. This argument is used to check if a line in the docstring is a valid item header and to parse the individual list items in the section. AnyItem
will be used by default.Returns: items (list) – List of the collected item instances of Item
type.
-
get_next_block
()[source]¶ Get the next item block from the docstring.
The method reads the next item block in the docstring. The first line is assumed to be the Item header and the following lines to belong to the definition body:
<header line> <definition>
The end of the field is designated by a line with the same indent as the field header or two empty lines in sequence.
-
goto_bookmark
(bookmark_index=-1)[source]¶ Move to bookmark.
Move the current index to the docstring line given by the
self.bookmarks[bookmark_index]
and remove it from the bookmark list. Default value will pop the last entry.Returns: bookmark (int)
-
insert_lines
(lines, index)[source]¶ Insert lines in the docstring.
Parameters: - lines (list) – The list of lines to insert
- index (int) – Index to start the insertion
-
parse
()[source]¶ Parse the docstring for sections.
The docstring is parsed for sections. If a section is found then the corresponding section rendering method is called.
-
peek
(ahead=0)[source]¶ Peek ahead a number of lines
The function retrieves the line that is ahead of the current index. If the index is at the end of the list then it returns an empty string.
Parameters: ahead (int) – The number of lines to look ahead.
-
docstring
Get the docstring lines.
-
eod
¶ End of docstring.
Sections¶
-
sectiondoc.sections.
attributes
(doc, header, renderer=<class 'sectiondoc.renderers.attribute.Attribute'>, item_class=<class 'sectiondoc.items.definition_item.DefinitionItem'>)[source]¶ Render the attributes section to sphinx friendly format.
Parameters:
-
sectiondoc.sections.
notes_paragraph
(doc, header, renderer=None, item_class=None)[source]¶ Render the note section to use the rst
.. note
directive.The section is expected to be given as a paragraph.
-
sectiondoc.sections.
methods_table
(doc, header, renderer=<class 'sectiondoc.renderers.method.Method'>, item_class=<class 'sectiondoc.items.method_item.MethodItem'>)[source]¶ Render the methods section to sphinx friendly table format.
-
sectiondoc.sections.
rubric
(doc, header, renderer=None, item_class=None)[source]¶ Refactor a header section using the rubric directive.
The method supports refactoring of single word headers, two word headers and headers that include a backslash ‘’‘’.
Parameters: header (string) – The header string to use with the rubric directive.
-
sectiondoc.sections.
arguments
(doc, header, renderer=<class 'sectiondoc.renderers.argument.Argument'>, item_class=<class 'sectiondoc.items.definition_item.DefinitionItem'>)[source]¶ Render the argument section to sphinx friendly format.
Parameters:
-
sectiondoc.sections.
item_list
(doc, header, renderer=<class 'sectiondoc.renderers.list_item.ListItem'>, item_class=<class 'sectiondoc.items.or_definition_item.OrDefinitionItem'>)[source]¶ Render the section to sphinx friendly item list.
Parameters: - 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
OrDefinitionItem
.
Items¶
-
class
sectiondoc.items.
OrDefinitionItem
[source]¶ A docstring definition section item.
In this section definition item there are two classifiers that are separated by
or
.Syntax diagram:
+-------------------------------------------------+ | term [ " : " classifier [ " or " classifier] ] | +--+----------------------------------------------+---+ | definition | | (body elements)+ | +--------------------------------------------------+
-
term
= str¶ The term usually reflects the name of a parameter or an attribute.
-
classifiers
= list¶ The classifiers of the definition. Commonly used to reflect the type of an argument or the signature of a function. Only two classifiers are accepted.
-
definition
= list¶ The list of strings that holds the description the definition item.
Note
An Or Definition item is based on the item of a section definition list as it defined in restructured text (_http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections).
Create new instance of Item(term, classifiers, definition)
-
classmethod
is_item
(line)[source]¶ Check if the line is describing a definition item.
The method is used to check that a line is following the expected format for the term and classifier attributes.
The expected format is:
+-------------------------------------------------+ | term [ " : " classifier [ " or " classifier] ] | +-------------------------------------------------+
Subclasses can restrict or expand this format.
-
classmethod
parse
(lines)[source]¶ Parse a definition item from a set of lines.
The class method parses the definition list item from the list of docstring lines and produces a DefinitionItem with the term, classifier and the definition.
Note
The global indention in the definition lines is striped
The term definition is assumed to be in one of the following formats:
term Definition.
term Definition, paragraph 1. Definition, paragraph 2.
term : classifier Definition.
term : classifier or classifier Definition.
- lines
- docstring lines of the definition without any empty lines before or after.
Returns: definition (OrDefinitionItem)
-
-
class
sectiondoc.items.
DefinitionItem
[source]¶ A docstring definition section item.
In this section definition item, multiple classifiers can be provided as shown in the diagram below.
Syntax diagram:
+-----------------------------+ | term [ " : " classifier ]* | +--+--------------------------+---+ | definition | | (body elements)+ | +------------------------------+
-
term
= str¶ The term usually reflects the name of a parameter or an attribute.
-
classifiers
= list¶ The classifiers of the definition. Commonly used to reflect the type of an argument or the signature of a function. Multiple classifiers are allowed separated by colons `` : ``.
-
definition
= list¶ The list of strings that holds the description the definition item.
Create new instance of Item(term, classifiers, definition)
-
classmethod
is_item
(line)[source]¶ Check if the line is describing a definition item.
The method is used to check that a line is following the expected format for the term and classifier attributes.
The expected format is:
+----------------------------+ | term [ " : " classifier ]* | +----------------------------+
Subclasses can restrict or expand this format.
-
classmethod
parse
(lines)[source]¶ Parse a definition item from a set of lines.
The class method parses the definition list item from the list of docstring lines and produces a DefinitionItem with the term, classifier and the definition.
Note
The global indention in the definition lines is striped
The term definition is assumed to be in one of the following formats:
term Definition.
term Definition, paragraph 1. Definition, paragraph 2.
term : classifier Definition.
term : classifier : classifier Definition.
- lines
- docstring lines of the definition without any empty lines before or after.
Returns: definition (DefinitionItem)
-
-
class
sectiondoc.items.
MethodItem
[source]¶ A MethodItem for method descriptions.
-
term
= str¶ The term usually reflects the name of the method.
-
classifiers
= list¶ The classifiers reflect the signature (i.e args and kwargs) of the method.
-
definition
= list¶ The list of strings that holds the description the method item.
Create new instance of Item(term, classifiers, definition)
-
classmethod
is_item
(line)[source]¶ Check if the definition header is a function signature.
The expected header has the following format:
+---------------------------------------------+ | term "(" [ classifier [, classifier]* ] ")" | +---------------------------------------------+
-
classmethod
parse
(lines)[source]¶ Parse a method definition item from a set of lines.
Parse the method signature and definition from the list of docstring lines and produce a MethodItem where the
term
is the method name and the classifier is arguments.Note
The global indention in the definition lines is striped
The format of the method definition item is expected to be as follows:
+---------------------------------------------+ | term "(" [ classifier [, classifier]* ] ")" | +--+--------------------------------------+---+ | definition | | (body elements)+ | +--------------------------------------+
Parameters: lines – docstring lines of the method definition item without any empty lines before or after. Returns: definition (MethodItem)
-
-
class
sectiondoc.items.
AnyItem
[source]¶ A docstring definition section item.
In this section item the are not restrictions on the classifier’s section of the item header.
Syntax diagram:
+-------------------------------------------------+ | term [ " : " text ] | +--+----------------------------------------------+---+ | definition | | (body elements)+ | +--------------------------------------------------+
-
term
= str¶ The term usually reflects the name of a parameter or an attribute.
-
classifiers
= list¶ The classifiers of the definition. Commonly used to reflect the type of an argument or the signature of a function. Any text after the ` : ` till the end of the line is consider a single classifier.
-
definition
= list¶ The list of strings that holds the description the definition item.
Note
AnyItem is probably closer to numpydoc on describing a section item.
Create new instance of Item(term, classifiers, definition)
-
classmethod
is_item
(line)[source]¶ Check if the line is describing a definition item.
The method is used to check that a line is following the expected format for the term and classifier attributes.
The expected format is:
+-------------------------------------------------+ | term [ " : " text ] | +-------------------------------------------------+
Subclasses can restrict or expand this format.
-
classmethod
parse
(lines)[source]¶ Parse a definition item from a set of lines.
The class method parses the definition list item from the list of docstring lines and produces a DefinitionItem with the term, classifier and the definition.
Note
The global indention in the definition lines is striped.
The term definition is assumed to be in one of the following formats:
term Definition.
term : Definition.
term Definition, paragraph 1. Definition, paragraph 2.
- ::
- term:
Definition, paragraph 1.
Definition, paragraph 2.
term : any text is valid here Definition.
- lines
- docstring lines of the definition without any empty lines before or after.
Returns: definition (AnyItem)
-
-
class
sectiondoc.items.
Item
[source]¶ A section item.
The Item class is responsible to check, parse a docstring item into a (term, classifiers, definition) tuple.
Format diagram:
+-------------------------------------------------+ | header | +--+----------------------------------------------+---+ | definition | | (body elements)+ | +--------------------------------------------------+
Depending only in the type of the list item the header is split into a term and one or more classifiers.
-
term
= str¶ The term usually reflects the name of a parameter or an attribute.
-
classifiers
= list¶ The classifier(s) of the term. Commonly used to reflect the type of an argument or the signature of a function.
-
definition
= list¶ The list of strings that holds the description of the definition item.
Create new instance of Item(term, classifiers, definition)
-
classmethod
is_item
(line)[source]¶ Check if the line is describing an item.
The method is used to check that a line is following the expected format for the
term
andclassifiers
attributes.
-
classmethod
parse
(lines)[source]¶ Parse a definition item from a set of lines.
The class method parses the item from the list of docstring lines and produces a Item with the term, classifier and the definition.
Note
The global indention in the definition lines is striped
Parameters: lines – docstring lines of the definition without any empty lines before or after. Returns: item (Item)
-
Renderers¶
-
class
sectiondoc.renderers.
Method
(item=None)[source]¶ Render method items as a table row.
-
to_rst
(columns=(0, 0))[source]¶ Outputs definition in rst as a line in a table.
Parameters: columns (tuple) – The two item tuple of column widths for the :meth: role column and the definition (i.e. summary) of the MethodItem Note
The string attributes are clipped to the column width.
Example
>>> item = MethodItem('function', 'arg1, arg2', ... ['This is the best function ever.']) >>> renderer = Method(item) >>> renderer.to_rst(columns=(40, 20)) :meth:`function <function(arg1, arg2)>` This is the best fun
-
-
class
sectiondoc.renderers.
Argument
(item=None)[source]¶ Render an item as a sphinx parameter role.
-
to_rst
()[source]¶ 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
to_rst()
method.
-
-
class
sectiondoc.renderers.
Renderer
(item=None)[source]¶ An item renderer.
-
to_rst
(**kwards)[source]¶ Outputs the item in sphinx friendly rst.
The method renders the passed into a list of lines that follow the rst markup.
Subclasses need to override the method to provide their custom made behaviour. However the signature of the method should hold only keyword arguments which always have default values.
Returns: lines (list) – A list of string lines rendered in rst.
-
-
class
sectiondoc.renderers.
Attribute
(item=None)[source]¶ Render an Item instance using the sphinx attribute directive.
-
to_rst
()[source]¶ 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.
-
-
class
sectiondoc.renderers.
ListItem
(item=None)[source]¶ Rendered an item instance as an ordered/unordered list item.
-
to_rst
(prefix=None)[source]¶ Renders an item as items in an rst list.
Parameters: 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.
-
-
class
sectiondoc.renderers.
TableRow
(item=None)[source]¶ Render an Item that represents a table line.
-
to_rst
(columns=(0, 0, 0))[source]¶ Outputs definition in rst as a line in a table.
Parameters: columns (tuple) – The three item tuple of column widths for the term, classifiers and definition fields of the TableLineItem. When the column width is 0 then the field is ignored. Note
- The strings attributes are clipped to the column width.
Example
>>> item = Item('function(arg1, arg2)', '', ... ['This is the best function ever.']) >>> TableRow(item).to_rst(columns=(22, 0, 20)) function(arg1, arg2) This is the best fun
-
-
class
sectiondoc.renderers.
Definition
(item=None)[source]¶ Render an Item instance as a sphinx definition term
-
to_rst
(**kwards)[source]¶ 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.
-