Library Reference¶
The extension is separated into three main parts.
Sphinx extension¶
Refactor classes¶
-
class
refactordoc.base_doc.
BaseDoc
(lines, headers=None)[source]¶ Base abstract docstring refactoring class.
The class’ main purpose is to parse the docstring and find the sections that need to be refactored. Subclasses should provide the methods responsible for refactoring the sections.
-
docstring
= list¶ A list of strings (lines) that holds docstrings
-
index
= int¶ The current zero-based line number of the docstring that is currently processed.
-
headers
= dict¶ The sections that the class will refactor. Each entry in the dictionary should have as key the name of the section in the form that it appears in the docstrings. The value should be the postfix of the method, in the subclasses, that is responsible for refactoring (e.g. {‘Methods’: ‘method’}).
BaseDoc also provides a number of methods that operate on the docstring to help with the refactoring. This is necessary because the docstring has to change inplace and thus it is better to live the docstring manipulation to the class methods instead of accessing the lines directly.
-
docstring
Get the docstring lines.
-
eod
¶ End of docstring.
-
extract_items
(item_class=None)[source]¶ Extract the definition items from a docstring.
Parse the items in the description of a section into items of the provided class time. Given a DefinitionItem or a subclass defined by the
item_class
parameter. Staring from the current index position, the method checks if in the next two lines a valid header exists. If successful, then the lines that belong to the item description block (i.e. header + definition) are popped out from the docstring and passed to theitem_class
parser and create an instance ofitem_class
.The process is repeated until there is no compatible
item_class
found or we run out of docstring. Then the method returns a list of item_class instances.The 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_class (DefinitionItem) – A DefinitionItem or a subclass. This argument is used to check if a line in the docstring is a valid item and to parse the individual list items in the section. When None
(default) the base DefinitionItem class is used.Returns: parameters (list) – List of the parsed item instances of item_class
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 DefinitionItem header and the following lines to belong to the definition:
<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 are found in sequence.
-
goto_bookmark
(bookmark_index=-1)[source]¶ Move to bookmark.
Move the current index to the docstring line given my the
self.bookmarks[bookmark_index]
and remove it from the bookmark list. Default value will pop the last entry.Returns: bookmark (int)
-
parse
()[source]¶ Parse the docstring.
The docstring is parsed for sections. If a section is found then the corresponding refactoring method is called.
-
-
class
refactordoc.function_doc.
FunctionDoc
(lines, headers=None)[source]¶ Docstring refactoring for functions
The class provides the following refactoring methods.
Method Description _refactor_arguments(self, header)
Refactor the Arguments and Parameters section to sphinx friendly format. _refactor_as_items_list(self, header)
Refactor the Returns, Raises and Yields sections to sphinx friendly format. _refactor_notes(self, header)
Refactor the note section to use the rst .. note
directive.-
_refactor_arguments
(header)[source]¶ Refactor the argument section to sphinx friendly format.
Parameters: header (unused) – This parameter is ignored in thi method.
-
-
class
refactordoc.class_doc.
ClassDoc
(lines, headers=None)[source]¶ Docstring refactoring for classes.
The class provides the following refactoring methods.
Method Description _refactor_attributes(self, header)
Refactor the attributes section to sphinx friendly format. _refactor_methods(self, header)
Refactor the methods section to sphinx friendly format. _refactor_notes(self, header)
Refactor the note section to use the rst .. note
directive.-
_get_column_lengths
(items)[source]¶ Helper function to estimate the column widths for the refactoring of the
Methods
section.The method finds the index of the item that has the largest function name (i.e. self.term) and the largest signature. If the indexes are not the same then checks to see which of the two items have the largest string sum (i.e. self.term + self.signature).
-
Definition items¶
-
class
refactordoc.definition_items.
ArgumentItem
[source]¶ A definition item for function argument sections.
-
to_rst
()[source]¶ Render ArgumentItem in sphinx friendly rst using the
:param:
role.Example
>>> item = ArgumentItem('indent', 'int', ... ['The indent to use for the description block.', '' 'This is the second paragraph of the argument definition.']) >>> item.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
refactordoc.definition_items.
AttributeItem
[source]¶ Definition that renders the rst output using the attribute directive.
-
to_rst
()[source]¶ Return the attribute info using the attribute sphinx markup.
Examples
>>> item = AttributeItem('indent', 'int', ... ['The indent to use for the description block.']) >>> item.to_rst() .. attribute:: indent :annotation: = int The indent to use for the description block >>>
>>> item = AttributeItem('indent', '', ... ['The indent to use for the description block.']) >>> 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
refactordoc.definition_items.
DefinitionItem
[source]¶ A docstring definition item
Syntax diagram:
+-------------------------------------------------+ | term [ " : " classifier [ " or " classifier] ] | +--+----------------------------------------------+---+ | definition | | (body elements)+ | +--------------------------------------------------+
The Definition class is based on the nametuple class and is responsible to check, parse and refactor a docstring definition item into sphinx friendly rst.
-
term
= str¶ The term usually reflects the name of a parameter or an attribute.
- classifier: str
The classifier of the definition. Commonly used to reflect the type of an argument or the signature of a function.
Note
Currently only one classifier is supported.
- definition : list
- The list of strings that holds the description the definition item.
Note
A 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).
-
classmethod
is_definition
(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 subclass to 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.
- lines
- docstring lines of the definition without any empty lines before or after.
Returns: definition (DefinitionItem)
-
to_rst
(**kwards)[source]¶ Outputs the Definition in sphinx friendly rst.
The method renders the definition into a list of lines that follow the rst markup. The default behaviour is to render the definition as an sphinx definition item:
<term> (<classifier>) -- <definition>
Subclasses will usually override the method to provide custom made behaviour. However the signature of the method should hold only keyword arguments which have default values. The keyword arguments can be used to pass addition rendering information to subclasses.
Returns: lines (list) – A list of string lines rendered in rst. Example
>>> item = DefinitionItem('lines', 'list', ['A list of string lines rendered in rst.']) >>> item.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.
-
-
class
refactordoc.definition_items.
ListItem
[source]¶ A definition item that is rendered as an ordered/unordered list
-
to_rst
(prefix=None)[source]¶ Outputs ListItem in rst using as items in an list.
Parameters: prefix (str) – The prefix to use. For example if the item is part of a numbered list then prefix='-'
.Example
>>> item = ListItem('indent', 'int', ... ['The indent to use for the description block.']) >>> item.to_rst(prefix='-') - **indent** (`int`) -- The indent to use for the description block.
>>> item = ListItem('indent', 'int', ... ['The indent to use for' 'the description block.']) >>> item.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
refactordoc.definition_items.
MethodItem
[source]¶ A TableLineItem subclass to parse and render class methods.
-
classmethod
parse
(lines)[source]¶ Parse a method definition item from a set of lines.
The class method parses the method signature and definition from the list of docstring lines and produces 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 method definition item is assumed to be as follows:
+------------------------------+ | term "(" [ classifier ] ")" | +--+---------------------------+---+ | definition | | (body elements)+ | +--------------------- ---------+
Parameters: lines – docstring lines of the method definition item without any empty lines before or after. Returns: definition (MethodItem)
-
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 strings attributes are clipped to the column width.
Example
>>> item = MethodItem('function', 'arg1, arg2', ... ['This is the best function ever.']) >>> item.to_rst(columns=(40, 20)) :meth:`function <function(arg1, arg2)>` This is the best fun
-
classmethod
-
class
refactordoc.definition_items.
TableLineItem
[source]¶ A Definition 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, classifier and definition fields of the TableLineItem. When the column width is 0 then the field Note
- The strings attributes are clipped to the column width.
Example
>>> item = TableLineItem('function(arg1, arg2)', '', ... ['This is the best function ever.']) >>> item.to_rst(columns=(22, 0, 20)) function(arg1, arg2) This is the best fun
-
Line functions¶
-
refactordoc.line_functions.
add_indent
(lines, indent=4)[source]¶ Add spaces to indent a list of lines.
Parameters: Returns: lines (list) – The indented strings (lines).
Note
Empty strings are not changed.
-
refactordoc.line_functions.
fix_backspace
(word)[source]¶ Replace
\
with\\
so that it will printed properly in the documentation.
-
refactordoc.line_functions.
fix_star
(word)[source]¶ Replace
*
with\*
so that is will be parse properly by docutils.
-
refactordoc.line_functions.
fix_trailing_underscore
(word)[source]¶ Replace the trailing
_
with\_
so that it will printed properly in the documentation.
-
refactordoc.line_functions.
remove_indent
(lines)[source]¶ Remove all indentation from the lines.
Returns: result (list) – A new list of left striped strings.
-
refactordoc.line_functions.
replace_at
(word, line, index)[source]¶ Replace the text in-line.
The text in line is replaced (not inserted) with the word. The replacement starts at the provided index. The result is cliped to the input length
Parameters: Returns: result (str) – line of text with the text replaced.