Docconvert

Update or convert docstrings in existing Python files.

This Python (3.9+) 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.

Python 2.7

We tried really hard to have this package support both Python 2 and 3 for a
long time. We’ve dropped Python 2 support officially. Its just become
cumbersome to automate tests for. However, the code will probably still
work in Python 2.7+ I think. Good luck!

License

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