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.

Files for docconvert, version 2.0.0
Filename, size File type Python version Upload date Hashes
Filename, size docconvert-2.0.0-py2.py3-none-any.whl (32.9 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size docconvert-2.0.0.tar.gz (27.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page