Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/PyCQA/docformatter

Formats docstrings to follow PEP 257
https://github.com/PyCQA/docformatter

autoformat docstring formatter python

Last synced: about 1 month ago
JSON representation

Formats docstrings to follow PEP 257

Host: GitHub
URL: https://github.com/PyCQA/docformatter
Owner: PyCQA
License: mit
Created: 2012-05-26T21:40:48.000Z (about 12 years ago)
Default Branch: master
Last Pushed: 2024-02-27T16:36:54.000Z (4 months ago)
Last Synced: 2024-04-16T05:07:03.994Z (2 months ago)
Topics: autoformat, docstring, formatter, python
Language: Python
Homepage: https://pypi.python.org/pypi/docformatter
Size: 824 KB
Stars: 502
Watchers: 9
Forks: 57
Open Issues: 26
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.md
- License: LICENSE

Lists

awesome-python-code-formatters - docformatter
best-of-python-dev - GitHub - 16% open · ⏱️ 15.10.2023): (Code Formatters)
awesome-stars - PyCQA/docformatter - `★519` Formats docstrings to follow PEP 257 (Python)

README

        ============

docformatter

============

.. |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/

Features

========

``docformatter`` automatically formats docstrings to follow a subset of the PEP

257 conventions. Below are the relevant items quoted from PEP 257.

- For consistency, always use triple double quotes around docstrings.

- Triple quotes are used even though the string fits on one line.

- Multi-line docstrings consist of a summary line just like a one-line

  docstring, followed by a blank line, followed by a more elaborate

  description.

- Unless the entire docstring fits on a line, place the closing quotes

  on a line by themselves.

``docformatter`` also handles some of the PEP 8 conventions.

- Don't write string literals that rely on significant trailing

  whitespace. Such trailing whitespace is visually indistinguishable

  and some editors (or more recently, reindent.py) will trim them.

``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

Installation

============

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@

Where  is the release candidate tag you'd like to install.  Release

candidate tags will have the format v1.6.0-rc1  Release candidates will also be

made available as a Github Release.

Example

=======

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()

Marketing

=========

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

Issues

======

Bugs and patches can be reported on the `GitHub page`_.

.. _`GitHub page`: https://github.com/PyCQA/docformatter/issues