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
"""
BaseDoc.insert_lines(lines, index)[source]

Insert refactored lines

Parameters:
  • 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.
refactordoc.line_functions.add_indent(lines, indent=4)[source]

Add spaces to indent a list of lines.

Parameters:
  • lines (list) – The list of strings to indent.
  • indent (int) – The number of spaces to add.
Returns:

lines (list) – The indented strings (lines).

Note

Empty strings are not changed.