.. |CI| image:: https://img.shields.io/github/actions/workflow/status/PyCQA/docformatter/ci.yml?branch=master :target: https://github.com/PyCQA/docformatter/actions/workflows/ci.yml .. |COVERALLS| image:: https://img.shields.io/coveralls/github/PyCQA/docformatter :target: https://coveralls.io/github/PyCQA/docformatter .. |CONTRIBUTORS| image:: https://img.shields.io/github/contributors/PyCQA/docformatter :target: https://github.com/PyCQA/docformatter/graphs/contributors .. |COMMIT| image:: https://img.shields.io/github/last-commit/PyCQA/docformatter .. |BLACK| image:: https://img.shields.io/badge/%20style-black-000000.svg :target: https://github.com/psf/black .. |ISORT| image:: https://img.shields.io/badge/%20imports-isort-%231674b1 :target: https://pycqa.github.io/isort/ .. |SELF| image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg :target: https://github.com/PyCQA/docformatter .. |SPHINXSTYLE| image:: https://img.shields.io/badge/%20style-sphinx-0a507a.svg :target: https://www.sphinx-doc.org/en/master/usage/index.html .. |NUMPSTYLE| image:: https://img.shields.io/badge/%20style-numpy-459db9.svg :target: https://numpydoc.readthedocs.io/en/latest/format.html .. |GOOGSTYLE| image:: https://img.shields.io/badge/%20style-google-3666d6.svg :target: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings
.. |VERSION| image:: https://img.shields.io/pypi/v/docformatter .. |LICENSE| image:: https://img.shields.io/pypi/l/docformatter .. |PYVERS| image:: https://img.shields.io/pypi/pyversions/docformatter .. |PYMAT| image:: https://img.shields.io/pypi/format/docformatter .. |DD| image:: https://img.shields.io/pypi/dd/docformatter .. |PRE| image:: https://img.shields.io/github/v/release/PyCQA/docformatter?include_prereleases
+----------------+----------------------------------------------------------+ | Code + |BLACK| |ISORT| + +----------------+----------------------------------------------------------+ | Docstrings + |SELF| |NUMPSTYLE| + +----------------+----------------------------------------------------------+ | GitHub + |CI| |CONTRIBUTORS| |COMMIT| |PRE| + +----------------+----------------------------------------------------------+ | PyPi + |VERSION| |LICENSE| |PYVERS| |PYMAT| |DD| + +----------------+----------------------------------------------------------+
Formats docstrings to follow PEP 257
_.
.. _PEP 257
: http://www.python.org/dev/peps/pep-0257/
docformatter
automatically formats docstrings to follow a subset of the PEP
257 conventions. Below are the relevant items quoted from PEP 257.
docformatter
also handles some of the PEP 8 conventions.
docformatter
formats docstrings compatible with black
when passed the
--black
option.
docformatter
formats field lists that use Epytext or Sphinx styles.
See the the full documentation at read-the-docs
, especially the
requirements
section for a more detailed discussion of PEP 257 and other
requirements.
.. _read-the-docs: https://docformatter.readthedocs.io .. _requirements: https://docformatter.readthedocs.io/en/latest/requirements.html
From pip::
$ pip install --upgrade docformatter
Or, if you want to use pyproject.toml to configure docformatter and you're using Python < 3.11::
$ pip install --upgrade docformatter[tomli]
With Python >=3.11, tomllib
from the standard library is used.
Or, if you want to use a release candidate (or any other tag)::
$ pip install git+https://github.com/PyCQA/docformatter.git@<RC_TAG>
Where
After running::
$ docformatter --in-place example.py
this code
.. code-block:: python
""" Here are some examples.
This module docstring should be dedented."""
def launch_rocket():
"""Launch
the
rocket. Go colonize space."""
def factorial(x):
'''
Return x factorial.
This uses math.factorial.
'''
import math
return math.factorial(x)
def print_factorial(x):
"""Print x factorial"""
print(factorial(x))
def main():
"""Main
function"""
print_factorial(5)
if factorial(10):
launch_rocket()
gets formatted into this
.. code-block:: python
"""Here are some examples.
This module docstring should be dedented.
"""
def launch_rocket():
"""Launch the rocket.
Go colonize space.
"""
def factorial(x):
"""Return x factorial.
This uses math.factorial.
"""
import math
return math.factorial(x)
def print_factorial(x):
"""Print x factorial."""
print(factorial(x))
def main():
"""Main function."""
print_factorial(5)
if factorial(10):
launch_rocket()
Do you use docformatter? What style docstrings do you use? Add some badges to your project's README and let everyone know.
|SELF|
.. code-block::
.. image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
:target: https://github.com/PyCQA/docformatter
|SPHINXSTYLE|
.. code-block::
.. image:: https://img.shields.io/badge/%20style-sphinx-0a507a.svg
:target: https://www.sphinx-doc.org/en/master/usage/index.html
|NUMPSTYLE|
.. code-block::
.. image:: https://img.shields.io/badge/%20style-numpy-459db9.svg
:target: https://numpydoc.readthedocs.io/en/latest/format.html
|GOOGSTYLE|
.. code-block::
.. image:: https://img.shields.io/badge/%20style-google-3666d6.svg
:target: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings
Bugs and patches can be reported on the GitHub page
_.
.. _GitHub page
: https://github.com/PyCQA/docformatter/issues