Docconvert

Update or convert docstrings in existing Python files.

This Python (2.7+/3.6+) module and script intends to help Python programmers to enhance internal code documentation using docstrings. It is useful to harmonize or change a project docstring style format.

It will parse one or several python scripts and retrieve existing docstrings. Then, for all found modules/functions/methods/classes, it will convert docstrings with parameters, returns, and other fields formatted in the newly specified style.

Currently, the managed styles in input/output are:

Input

• epytext
• reST (re-Structured Text, as used by Sphinx)

Output

• google
• numpy
• epytext
• reST (re-Structured Text, as used by Sphinx)

Getting Started

Installation

Docconvert can be installed through pip:

pip install docconvert

Usage

usage: docconvert [-h] [-i {guess,rest,epytext}] [-o {google,numpy,rest,epytext}]
                  [--in-place] [-c CONFIG] [-t THREADS] [-v]
                  source

positional arguments:
  source                The directory or file to convert.

optional arguments:
  -h, --help            show this help message and exit
  -i {guess,rest,epytext}, --input {guess,rest,epytext}
                        Input docstring style. (default: guess)
  -o {google,numpy,rest,epytext}, --output {google,numpy,rest,epytext}
                        Output docstring style to convert to. (default: google)
  --in-place            Write the changes to the input file instead of printing diffs.
  -c CONFIG, --config CONFIG
                        Location of configuration file to use.
  -t THREADS, --threads THREADS
                        Number of threads to use. (default: cpu count)
  -v, --verbose         Log more information.

Examples:

Convert files in src/mypackage to google using 4 threads.

docconvert --output google --threads 4 src/mypackage/

Convert file src/mypackage/myfile.py from rest to google.

docconvert --input rest --output google src/mypackage/myfile.py

Custom Configuration

You can configure optional conversion arguments in a json config file. Just specify a config filepath to the commandline tool.

docconvert --config path/to/config.json src/mypackage/

Detailed description of all configuration options can be found in the documentation.

Contributing

If you would like to contribute, please take a look at the contributor documentation.

Versioning

We use SemVer for versioning. For the versions available, see the tags on the repository.

License

This project is licensed under the BSD-3-Clause License. See the LICENSE.md file for details.