1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
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:
.. code-block:: console
$ 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:
.. code-block:: console
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:
.. image:: ../images/pycharm-file-watcher-configurations.png
:alt: 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:
.. _`pre-commit`: https://pre-commit.com/
.. code-block:: yaml
- 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.
.. _`python-lint-plus`: https://github.com/marketplace/actions/python-code-style-quality-and-lint
|
