Currently either installable from source, or by pip installing from github:
python -m pip install git+https://github.com/kremrik/doctr.git
Suppose you have a the following README
# Foo
Cool project
and the following Python module (foo.py
) you want people to use
"""a module to just print 'foo' as many times as you want"""
def foo(num: int):
"""A function that prints 'foo'
Example:
>>> from foo import foo
>>> foo(3)
# 'foofoofoo'
"""
print("foo" * num)
You can insert the documentation for foo.py
into your README by running
doctr -p /path/to/foo.py --level 2
which will update your README to the following
# Foo
Cool project
## foo
a module to just print 'foo' as many times as you want
### `foo`
A function that prints 'foo'
``python
>>> from foo import foo
>>> foo(3)
# 'foofoofoo'
``
usage: doctr.py [-h] --path PATH [--level LEVEL] [--readme README]
optional arguments:
-h, --help show this help message and exit
--path PATH, -p PATH [REQUIRED] Path to package or module
--level LEVEL, -l LEVEL
Number of '#' at top level
--readme README, -r README
Path to README to update
To properly format python examples in your docstrings, follow the Google-RST guide, which requires
any example block to be denoted with an Example:
or Examples:
block.
Any other specified blocks will be ignore, but any text at the top of the docstring will be included.
Any docstring at the top of a module will be included