doctr's Introduction

docstring-to-readme

Installation

Currently either installable from source, or by pip installing from github:

python -m pip install git+https://github.com/kremrik/doctr.git

Example

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'
``

CLI

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

Usage

Function-level documentation

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.