Skip to main content

Convert and conform package docstrings to a new style

Project description

Docconvert

Build Status Documentation PyPI Version Supported Python Versions Formatted with Black

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

Output

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docconvert-2.1.0.tar.gz (27.0 kB view hashes)

Uploaded source

Built Distribution

docconvert-2.1.0-py2.py3-none-any.whl (32.9 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page