{"id":18468752,"url":"https://github.com/pycqa/docformatter","last_synced_at":"2026-04-01T20:44:09.250Z","repository":{"id":3407773,"uuid":"4458025","full_name":"PyCQA/docformatter","owner":"PyCQA","description":"Formats docstrings to follow PEP 257","archived":false,"fork":false,"pushed_at":"2024-10-09T18:22:02.000Z","size":755,"stargazers_count":560,"open_issues_count":36,"forks_count":81,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-09T09:51:48.580Z","etag":null,"topics":["autoformat","docstring","formatter","python"],"latest_commit_sha":null,"homepage":"https://pypi.python.org/pypi/docformatter","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PyCQA.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-05-26T21:40:48.000Z","updated_at":"2025-04-07T17:52:25.000Z","dependencies_parsed_at":"2024-05-20T22:59:33.883Z","dependency_job_id":"88c1cdac-8c13-4f2b-a62e-41b52471011b","html_url":"https://github.com/PyCQA/docformatter","commit_stats":{"total_commits":576,"total_committers":32,"mean_commits":18.0,"dds":"0.27604166666666663","last_synced_commit":"504107bdc4618f83a3378faac610e02cd62ef5f9"},"previous_names":["myint/docformatter"],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyCQA%2Fdocformatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyCQA%2Fdocformatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyCQA%2Fdocformatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyCQA%2Fdocformatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PyCQA","download_url":"https://codeload.github.com/PyCQA/docformatter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248252658,"owners_count":21072699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autoformat","docstring","formatter","python"],"created_at":"2024-11-06T10:08:04.585Z","updated_at":"2026-04-01T20:44:09.236Z","avatar_url":"https://github.com/PyCQA.png","language":"Python","readme":"============\ndocformatter\n============\n\n.. |CI| image:: https://img.shields.io/github/actions/workflow/status/PyCQA/docformatter/ci.yml?branch=master\n    :target: https://github.com/PyCQA/docformatter/actions/workflows/ci.yml\n.. |COVERALLS| image:: https://img.shields.io/coveralls/github/PyCQA/docformatter\n    :target: https://coveralls.io/github/PyCQA/docformatter\n.. |CONTRIBUTORS| image:: https://img.shields.io/github/contributors/PyCQA/docformatter\n    :target: https://github.com/PyCQA/docformatter/graphs/contributors\n.. |COMMIT| image:: https://img.shields.io/github/last-commit/PyCQA/docformatter\n.. |BLACK| image:: https://img.shields.io/badge/%20style-black-000000.svg\n    :target: https://github.com/psf/black\n.. |ISORT| image:: https://img.shields.io/badge/%20imports-isort-%231674b1\n    :target: https://pycqa.github.io/isort/\n.. |SELF| image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg\n    :target: https://github.com/PyCQA/docformatter\n.. |SPHINXSTYLE| image:: https://img.shields.io/badge/%20style-sphinx-0a507a.svg\n    :target: https://www.sphinx-doc.org/en/master/usage/index.html\n.. |NUMPSTYLE| image:: https://img.shields.io/badge/%20style-numpy-459db9.svg\n    :target: https://numpydoc.readthedocs.io/en/latest/format.html\n.. |GOOGSTYLE| image:: https://img.shields.io/badge/%20style-google-3666d6.svg\n    :target: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings\n\n.. |VERSION| image:: https://img.shields.io/pypi/v/docformatter\n.. |LICENSE| image:: https://img.shields.io/pypi/l/docformatter\n.. |PYVERS| image:: https://img.shields.io/pypi/pyversions/docformatter\n.. |PYMAT| image:: https://img.shields.io/pypi/format/docformatter\n.. |DD| image:: https://img.shields.io/pypi/dd/docformatter\n.. |PRE| image:: https://img.shields.io/github/v/release/PyCQA/docformatter?include_prereleases\n\n+----------------+----------------------------------------------------------+\n| **Code**       + |BLACK| |ISORT|                                          +\n+----------------+----------------------------------------------------------+\n| **Docstrings** + |SELF| |NUMPSTYLE|                                       +\n+----------------+----------------------------------------------------------+\n| **GitHub**     + |CI| |CONTRIBUTORS| |COMMIT| |PRE|                       +\n+----------------+----------------------------------------------------------+\n| **PyPi**       + |VERSION| |LICENSE| |PYVERS| |PYMAT| |DD|                +\n+----------------+----------------------------------------------------------+\n\nFormats docstrings to follow `PEP 257`_.\n\n.. _`PEP 257`: http://www.python.org/dev/peps/pep-0257/\n\nFeatures\n========\n\n``docformatter`` automatically formats docstrings to follow a subset of the PEP\n257 conventions. Below are the relevant items quoted from PEP 257.\n\n- For consistency, always use triple double quotes around docstrings.\n- Triple quotes are used even though the string fits on one line.\n- Multi-line docstrings consist of a summary line just like a one-line\n  docstring, followed by a blank line, followed by a more elaborate\n  description.\n- Unless the entire docstring fits on a line, place the closing quotes\n  on a line by themselves.\n\n``docformatter`` also handles some of the PEP 8 conventions.\n\n- Don't write string literals that rely on significant trailing\n  whitespace. Such trailing whitespace is visually indistinguishable\n  and some editors (or more recently, reindent.py) will trim them.\n\n``docformatter`` formats docstrings compatible with ``black`` when passed the\n``--black`` option.\n\n``docformatter`` formats field lists that use Epytext or Sphinx styles.\n\nSee the the full documentation at `read-the-docs`_, especially the\n`requirements`_ section for a more detailed discussion of PEP 257 and other\nrequirements.\n\n.. _read-the-docs: https://docformatter.readthedocs.io\n.. _requirements: https://docformatter.readthedocs.io/en/latest/requirements.html\n\nInstallation\n============\n\nFrom pip::\n\n    $ pip install --upgrade docformatter\n\nOr, if you want to use pyproject.toml to configure docformatter and you're using\nPython \u003c 3.11::\n\n    $ pip install --upgrade docformatter[tomli]\n\nWith Python \u003e=3.11, ``tomllib`` from the standard library is used.\n\nOr, if you want to use a release candidate (or any other tag)::\n\n    $ pip install git+https://github.com/PyCQA/docformatter.git@\u003cRC_TAG\u003e\n\nWhere \u003cRC_TAG\u003e is the release candidate tag you'd like to install.  Release\ncandidate tags will have the format v1.6.0-rc1  Release candidates will also be\nmade available as a Github Release.\n\nExample\n=======\n\nAfter running::\n\n    $ docformatter --in-place example.py\n\nthis code\n\n.. code-block:: python\n\n    \"\"\"   Here are some examples.\n\n        This module docstring should be dedented.\"\"\"\n\n\n    def factorial(x):\n        '''\n\n        Return x factorial.\n\n        This uses math.factorial.\n\n        '''\n        import math\n        return math.factorial(x)\n\n\n    def print_factorial(x):\n        \"\"\"Print x factorial\"\"\"\n        print(factorial(x))\n\n\n    def main():\n        \"\"\"Main\n        function\"\"\"\n        print_factorial(5)\n        if factorial(10):\n            print_factorial(22)\n\n\ngets formatted into this\n\n.. code-block:: python\n\n    \"\"\"Here are some examples.\n\n    This module docstring should be dedented.\n    \"\"\"\n\n    def factorial(x):\n        \"\"\"Return x factorial.\n\n        This uses math.factorial.\n        \"\"\"\n        import math\n        return math.factorial(x)\n\n\n    def print_factorial(x):\n        \"\"\"Print x factorial.\"\"\"\n        print(factorial(x))\n\n\n    def main():\n        \"\"\"Main function.\"\"\"\n        print_factorial(5)\n        if factorial(10):\n            print_factorial(22)\n\nMarketing\n=========\nDo you use *docformatter*?  What style docstrings do you use?  Add some badges to your project's **README** and let everyone know.\n\n|SELF|\n\n.. code-block::\n\n    .. image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg\n        :target: https://github.com/PyCQA/docformatter\n\n|SPHINXSTYLE|\n\n.. code-block::\n\n    .. image:: https://img.shields.io/badge/%20style-sphinx-0a507a.svg\n        :target: https://www.sphinx-doc.org/en/master/usage/index.html\n\n|NUMPSTYLE|\n\n.. code-block::\n\n    .. image:: https://img.shields.io/badge/%20style-numpy-459db9.svg\n        :target: https://numpydoc.readthedocs.io/en/latest/format.html\n\n|GOOGSTYLE|\n\n.. code-block::\n\n    .. image:: https://img.shields.io/badge/%20style-google-3666d6.svg\n        :target: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings\n\nAssistance\n==========\n``docformatter`` has an IRC channel on `Libera.Chat`_ in the `#docformatter`_ room.\n .. _`Libera.Chat`: https://libera.chat\n .. _`#docformatter`: https://web.libera.chat/#docformatter\n\nThere is no ``docformatter`` channel on the Python Code Quality Discord server, but\nyou can ask for help in the `# general`_ channel.\n\n .. _`# general`: https://discord.com/channels/825463413634891776/934197425357336596\n\nIssues\n======\n\nBugs and patches can be reported on the `GitHub page`_.\n\n.. _`GitHub page`: https://github.com/PyCQA/docformatter/issues\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpycqa%2Fdocformatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpycqa%2Fdocformatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpycqa%2Fdocformatter/lists"}