# 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:

## 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.6.1
      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.