How to Configure docformatter

The command line options for docformatter can also be stored in a configuration file. Currently only pyproject.toml, setup.cfg, and tox.ini are supported. The configuration file can be passed with a full path. For example:

$ docformatter --config ~/.secret/path/to/pyproject.toml

If no configuration file is explicitly passed, docformatter will search the current directory for the supported files and use the first one found. The order of precedence is pyproject.toml, setup.cfg, then tox.ini.

In pyproject.toml, add a section [tool.docformatter] with options listed using the same name as command line argument. For example:

[tool.docformatter]
recursive = true
wrap-summaries = 82
blank = true

In setup.cfg or tox.ini, add a [docformatter] section.

[docformatter]
recursive = true
wrap-summaries = 82
blank = true

Command line arguments will take precedence over configuration file settings. For example, if the following is in your pyproject.toml

[tool.docformatter]
recursive = true
wrap-summaries = 82
wrap-descriptions = 81
blank = true

And you invoke docformatter as follows:

$ docformatter --config ~/.secret/path/to/pyproject.toml --wrap-summaries 68

Summaries will be wrapped at 68, not 82.

A Note on Options to Control Styles

There are various docformatter options that can be used to control the style of the docstring. These options can be passed on the command line or set in a configuration file. Currently, the style options are:

  • --black

  • -s or --style

When passing the --black option, the following arguments are set automatically:

  • --pre-summary-space is set to True

  • --wrap-descriptions is set to 88

  • --wrap-summaries is set to 88

All of these options can be overridden from the command line or in the configuration file. Further, the --pre-summary-space option only inserts a space before the summary when the summary begins with a double quote (“). For example:

"""This summary gets no space.""" becomes """This summary gets no space."""

and

""""This" summary does get a space.""" becomes """ "This" summary does get a space."""

The --style argument takes a string which is the name of the field list style you are using. Currently, only sphinx and epytext are recognized, but numpy and google are future styles. For the selected style, each line in the field lists will be wrapped at the --wrap-descriptions length as well as any portion of the elaborate description preceding the parameter list. Field lists that don’t follow the passed style will cause the entire elaborate description to be ignored and remain unwrapped.

A Note on reST Header Adornments Regex

docformatter-1.7.2 added a new option --rest-section-adorns. This allows for setting the characters used as overline and underline adornments for reST section headers. Per the ReStructuredText Markup Specification, the following are all valid adornment characters,

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

Thus, the default regular expression [!\"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]{4,} looks for any of these characters appearing at least four times in a row. Note that the list of valid adornment characters includes the double quote (”) and the greater-than sign (>). Four repetitions was selected because:

  • Docstrings open and close with triple double quotes.

  • Doctests begin with >>>.

  • It would be rare for a section header to consist of fewer than four characters.

The user can override this default list of characters by passing a regex from the command line or setting the rest-section-adorns option in the configuration file. It may be usefule to set this regex to only include the subset of characters you actually use in your docstrings. For example, to only recognize the recommended list in the ReStructuredText Markup Specification, the following regular expression would be used:

[=-`:.'"~^_*+#]{4,}