Default refactoring¶
The base implementation of RefactorDoc provides refactoring for class and
function doc-strings. A number of known (i.e. predefined) sections are processed
by the ClassDoc and FunctionDoc classes and all unknown sections are re-factored
using the .. rubric::
directive by default.
For class objects the ClassDoc
includes code to
re-factor three types of sections.
Heading | Description | Item | Max | Rendered as |
---|---|---|---|---|
Methods | Class methods with summary | MethodItem | – | Table with links to the method |
Attributes | Class attributes and their usage | Attribute | – | Sphinx attributes |
Notes | Useful notes | paragraph | 1 | Note admonition |
For function objects the FunctionDoc
includes
code to re-factor three types of sections.
Heading | Description | Item | Max | Rendered as |
---|---|---|---|---|
Arguments | function arguments and type | ArgumentItem | – | Parameters field list |
Returns | Return value | ListItem | – | Unordered list |
Raises | Raised exceptions | ListItem | – | Unordered list |
Notes | Useful notes | paragraph | 1 | Note admonition |
Usage rules¶
To be able to re-factor the sections properly the doc-strings should follow theses rules:
Rules
Between the section header and the first section item there can be at most only one empty line.
The end of the section is designated by one of the following:
The allowed number of items by the section has been parsed.
Two consecutive empty lines are found.
The line is not identified as a possible header of the section item.
Hint
Please check the doc-string of the specific definition item class to have more information regarding the valid item header format.
Examples¶
Argument sections¶
Arguments
---------
new_lines : list
The list of lines to insert
index : int
Index to start the insertion
"""
Method sections¶
Methods
-------
_refactor_attributes(self, header):
Re-factor the attributes section to sphinx friendly format.
_refactor_methods(self, header):
Re-factor the methods section to sphinx friendly format.
_refactor_notes(self, header):
Re-factor the note section to use the rst ``.. note`` directive.
Note
The table that is created in this example does not have the links
enabled because the methods are not rendered by autodoc (the
:no-members
option is set).
-
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.
Attribute sections¶
Attributes
----------
docstring : list
A list of strings (lines) that holds doc-strings
index : int
The current zero-based line number of the doc-string that is currently
processed.
headers : dict
The sections that the class re-factors. Each entry in the
dictionary should have as key the name of the section in the
form that it appears in the doc-strings. The value should be
the postfix of the method, in the subclasses, that is
responsible for refactoring (e.g. {'Methods': 'method'}).
-
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.
-
Returns sections¶
Returns
-------
result : list
A new list of left striped strings.
-
refactordoc.line_functions.
remove_indent
(lines)[source] Remove all indentation from the lines.
Returns: result (list) – A new list of left striped strings.
Raises section¶
Notes¶
Notes
-----
Empty strings are not changed.