# 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,}