[MarryDoc] Easy DocString Maintenance¶
The marrydoc
Python module makes maintaining consistency of
related Python docstrings easy. marrydoc
provides decorators to
“wed” a docstring to another and provides a command line tool to
automatically update a module’s docstrings when their basis docstrings
have changed.
The decorators offered annotate class, function, and method docstrings to identify if their docstring is to be inherited from, maintained as a copy of, or maintained as a modified copy of a docstring of another program construct.
Quick Start¶
@inherit¶
Use the inherit()
decorator to dynamically copy a docstring from
one program construct to another when a module is imported. For example:
import marrydoc
from foo import bar
@marrydoc.inherit(bar)
def my_bar():
pass
assert bar.__doc__ == my_bar.__doc__
@copied_from¶
Use the copied_from()
decorator in combination with the command line
tool to evaluate if one program construct docstring is up to date with
another and automatically update the script if they are unequal. For
example:
import marrydoc
from foo import bar
@marrydoc.copied_from(bar)
def my_bar():
"""Perform foo bar."""
pass
Then use the command line tool to evaluate if the source docstring has changed and automatically update if so:
$ python -m marrydoc --merge my_foo.py
my_foo.py ... OK
@based_on¶
Use the based_on()
decorator instead of copied_from()
when the docstring is a copy but has been modified. Pass an unmodified
copy of the source docstring as the second argument to based_on()
(to facilitate source docstring change detection and provide a basis of
a three way merge). For example:
import marrydoc
from foo import bar
@marrydoc.based_on(
bar,
"""Perform foo bar.""")
def my_bar():
"""Perform my special foo bar."""
pass
Then use the command line tool to evaluate if the source docstring has changed and automatically perform a three way merge if so:
$ python -m marrydoc --merge my_foo.py
my_foo.py ... UPDATED