pydocstringformatter 0.7.3

Description:

pydocstringformatter 0.7.3

Pydocstringformatter
A tool to automatically format Python docstrings to follow recommendations from
PEP 8 and
PEP 257 (or other supported style
guides.)
See What it does for currently supported auto-formatting.
Rationale
This project is heavily inspired by
docformatter.
When this project was started docformatter did not meet all of the requirements the
pylint project had for its docstring formatter and
was no longer actively maintained (this has changed since then). Therefore, some
contributors of pylint got together and started working on our own formatter to
fulfill our needs.
When asked we defined the objective of the tool as:
"A docstring formatter that follows PEP8 and PEP257 but makes some of the more
'controversial' elements of the PEPs optional"
See
the original answer.
As such, the biggest difference between the two is that pydocstringformatter fixes
some of the open issues we found in docformatter. In general, the output of both
formatters (and any other docstring formatter) should be relatively similar.
How to install
pip install pydocstringformatter

Usage
Click here for a
full Usage overview.
Configuration
Pydocstringformatter will also read any configuration added to the
[tool.pydocstringformatter] section of a pyproject.toml file.
For example:
[tool.pydocstringformatter]
write = true
exclude = "**/my_dir/**,**/my_other_dir/**"
# Or:
exclude = ["**/my_dir/**", "**/my_other_dir/**"]
strip-whitespaces = true
split-summary-body = false
numpydoc-section-hyphen-length = false

Style
Pydocstringformatter can be configured to use a specific style. The default is pep257
but we support other styles as well. These can also be used at the same time. For
example with:
pydocstringformatter --style=pep257 --style=numpydoc myfile.py

Pre-commit
Pydocstringformatter can also be used as a pre-commit hook.
Add the following to your .pre-commit-config.yaml file:
- repo: https://github.com/DanielNoord/pydocstringformatter
rev: SPECIFY VERSION HERE
hooks:
- id: pydocstringformatter

What it does
The following examples show some of the changes pydocstringformatter will apply. For a
full overview of all potential changes you can check out the
Usage page which
shows an up to date list of all formatters and their description.
# Bad
'''
my docstring'''

""" my
multi-line docstring """

"""my title
===========

my docstring
"""


# Good
"""My docstring."""

"""My
multi-line docstring.
"""

"""My title
===========

My docstring
"""

# With --summary-quotes-same-line
# Bad
"""
My
multi-line docstring
"""

# Good
"""My
multi-line docstring
"""

Development
For development and contributing guidelines please see
Development.