How to Use docformatter

There are several ways you can use docformatter. You can use it from the command line, as a file watcher in PyCharm, in your pre-commit checks, and as a GitHub action. However, before you can use docformatter, you’ll need to install it.

Use from the Command Line

To use docformatter from the command line, simply:

$ docformatter name_of_python_file.py

docformatter recognizes a number of options for controlling how the tool runs as well as how it will treat various patterns in the docstrings. The help output provides a summary of these options:

usage: docformatter [-h] [-i | -c] [-d] [-r] [-e [EXCLUDE ...]]
                    [-n [NON-CAP ...]] [-s [style]] [--rest-section-adorns REGEX]
                    [--black] [--wrap-summaries length]
                    [--wrap-descriptions length] [--force-wrap]
                    [--tab-width width] [--blank] [--pre-summary-newline]
                    [--pre-summary-space] [--make-summary-multi-line]
                    [--close-quotes-on-newline] [--range line line]
                    [--docstring-length length length] [--non-strict]
                    [--config CONFIG] [--version] files [files ...]

Formats docstrings to follow PEP 257.

positional arguments:
  files                 files to format or '-' for standard in

optional arguments:
  -h, --help            show this help message and exit
  -i, --in-place        make changes to files instead of printing diffs
  -c, --check           only check and report incorrectly formatted files
  -r, --recursive       drill down directories recursively
  -e, --exclude         in recursive mode, exclude directories and files by names
  -n, --non-cap         list of words not to capitalize when they appear as the
                        first word in the summary

  -s style, --style style
                        the docstring style to use when formatting parameter
                        lists.  One of epytext, sphinx. (default: sphinx)
  --rest-section-adorns REGEX
                        regular expression for identifying reST section adornments
                        (default: [!\"#$%&'()*+,-./\\:;<=>?@[]^_`{|}~]{4,})
  --black               make formatting compatible with standard black options
                        (default: False)
  --wrap-summaries length
                        wrap long summary lines at this length; set to 0 to
                        disable wrapping (default: 79, 88 with --black option)
  --wrap-descriptions length
                        wrap descriptions at this length; set to 0 to disable
                        wrapping (default: 72, 88 with --black option)
  --force-wrap
                        force descriptions to be wrapped even if it may result
                        in a mess (default: False)
  --tab_width width
                        tabs in indentation are this many characters when
                        wrapping lines (default: 1)
  --blank
                        add blank line after elaborate description
                        (default: False)
  --pre-summary-newline
                        add a newline before one-line or the summary of a
                        multi-line docstring
                        (default: False)
  --pre-summary-space
                        add a space between the opening triple quotes and
                        the first word in a one-line or summary line of a
                        multi-line docstring
                        (default: False)
  --make-summary-multi-line
                        add a newline before and after a one-line docstring
                        (default: False)
  --close-quotes-on-newline
                        place closing triple quotes on a new-line when a
                        one-line docstring wraps to two or more lines
                        (default: False)
  --range start_line end_line
                        apply docformatter to docstrings between these lines;
                        line numbers are indexed at 1
  --docstring-length min_length max_length
                        apply docformatter to docstrings of given length range
  --non-strict
                        do not strictly follow reST syntax to identify lists
                        (see issue #67) (default: False)
  --config CONFIG
                        path to file containing docformatter options
                        (default: ./pyproject.toml)
  --version
                        show program's version number and exit

Possible exit codes from docformatter:

  • 1 - if any error encountered

  • 2 - if it was interrupted

  • 3 - if any file needs to be formatted (in --check or --in-place mode)

Use as a PyCharm File Watcher

docformatter can be configured as a PyCharm file watcher to automatically format docstrings on saving python files.

Head over to Preferences > Tools > File Watchers, click the + icon and configure docformatter as shown below:

PyCharm file watcher configurations

Use with pre-commit

docformatter is configured for pre-commit and can be set up as a hook with the following .pre-commit-config.yaml configuration:

- repo: https://github.com/PyCQA/docformatter
  rev: v1.7.5
  hooks:
    - id: docformatter
      additional_dependencies: [tomli]
      args: [--in-place, --config, ./pyproject.toml]

You will need to install pre-commit and run pre-commit install.

Whether you use args: [--check] or args: [--in-place], the commit will fail if docformatter processes a change. The --in-place option fails because pre-commit does a diff check and fails if it detects a hook changed a file. The --check option fails because docformatter returns a non-zero exit code.

The additional_dependencies: [tomli] is only required if you are using pyproject.toml for docformatter’s configuration.

Use with GitHub Actions

docformatter is one of the tools included in the python-lint-plus action.

Dostring Text Patterns

docformatter began as a simple tool to format docstrings to follow PEP257. It was originally a single Python script of 118 lines containing seven functions. That’s no longer the case as an inspection of the codebase will show. Over time, docformatter has grown to include a number of features that have been requested by its most fantastic user base.

In the early days, docformatter only formatted simple docstrings. “Complex” text patterns like lists, parameter descriptions, and reStructuredText (reST) sections caused docformatter to simply skip formatting the docstring. As feature requests have been and will be incorporated, docformatter has gained the ability to recognize and format more complex text patterns.

As a result, it is necessary for the user to properly format their docstrings to follow the patterns documented in the various specifications. These specifications would include:

Any docstring that does not follow these specifications may not be formatted properly as these patterns may be recognized by docformatter as simple text that needs to formatted. For example, if a user writes a docstring that contains a list but does not format the list according to reST specifications, docformatter may not recognize the list and may format the list items as simple text. This could result in a list that is not properly indented or wrapped.

The user is encouraged to read and follow these specifications when writing docstrings to ensure that docformatter can properly format them. Issues reported to the docformatter project that are the result of docstrings not following these specifications will be closed as S:wontfix with a request for the user to update their docstrings to follow the specifications.

Additionally, as docformatter continues to add support for more text patterns (e.g., Numpy or Google style docstrings), new releases may result in significant docstring formatting changes in your code base. While we hate to see this happen to our users, it is the result of our desire to make docformatter the best tool it can be for formatting docstrings and the best way to achieve that is to strigently comply with the various specifications. We appreciate your understanding and patience as we continue to improve docformatter.