Building your own suite¶
While the default refactoring suite is enough for most cases. The user might need to extent the section repertoire, process other object types, allow more freedom in defining the definition list or restrict the docstring style to improve consinstancy through his code.
Warning
All the methods below require to change the refactordoc code and even thought the changes might be small it is not considered the best way since updating refactordoc becomes non-trivial. Future version will remove this shortcoming.
Adding sections¶
New sections to be refactored can be simply added to the headers
dictionary
when an appropriate refactoring method exists. For example in the default
suite that is shipped with refactordoc the
FunctionDoc
class sets the Returns
Raises and Yields section to use the _refactor_as_item_list method
in the class:
if headers is None:
headers = {'Returns': 'as_item_list', 'Arguments': 'arguments',
'Parameters': 'arguments', 'Raises': 'as_item_list',
'Yields': 'as_item_list', 'Notes':'notes'}
When such a method does not
exist then the user has to augment the related class with that will
parse and extract the section definition block(s) and return the
refactored lines as a list of strings to replace the section in the
docstring. The signature of the method should be
_header_<name>(self, header)
Where <name>
is the value in the headers
that corresponds to the
header
string that is found in the docstring.
Note
More to come