============
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@<RC_TAG>
Where <RC_TAG> 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
Raw data
{
"_id": null,
"home_page": "https://github.com/PyCQA/docformatter",
"name": "docformatter",
"maintainer": "Doyle Rowland",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "doyle.rowland@reliaqual.com",
"keywords": "PEP 257,pep257,style,formatter,docstrings",
"author": "Steven Myint",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b8/52/834e31b25d6a493da6b3cfeb2364aeeb07f8c5788d3ace7f7808a0c58d8d/docformatter-1.7.4.tar.gz",
"platform": null,
"description": "============\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 < 3.11::\n\n $ pip install --upgrade docformatter[tomli]\n\nWith Python >=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@<RC_TAG>\n\nWhere <RC_TAG> 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 launch_rocket():\n \"\"\"Launch\n the\n rocket. Go colonize space.\"\"\"\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 launch_rocket()\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\n def launch_rocket():\n \"\"\"Launch the rocket.\n\n Go colonize space.\n \"\"\"\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 launch_rocket()\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\nIssues\n======\n\nBugs and patches can be reported on the `GitHub page`_.\n\n.. _`GitHub page`: https://github.com/PyCQA/docformatter/issues\n\n",
"bugtrack_url": null,
"license": "Expat",
"summary": "Formats docstrings to follow PEP 257",
"version": "1.7.4",
"project_urls": {
"Documentation": "https://docformatter.readthedocs.io/en/latest/",
"Homepage": "https://github.com/PyCQA/docformatter",
"Repository": "https://github.com/PyCQA/docformatter"
},
"split_keywords": [
"pep 257",
"pep257",
"style",
"formatter",
"docstrings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "84b21844950043f108297b5dba1adcf675407977acc5f2622f5e0c0072822d00",
"md5": "63fb1bb956acfbb38e0b05383daece4c",
"sha256": "e91f99772562f583723272180deab65940bceec65570a3f2ab72695e80d9d4d0"
},
"downloads": -1,
"filename": "docformatter-1.7.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63fb1bb956acfbb38e0b05383daece4c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 32795,
"upload_time": "2023-07-10T13:48:08",
"upload_time_iso_8601": "2023-07-10T13:48:08.773946Z",
"url": "https://files.pythonhosted.org/packages/84/b2/1844950043f108297b5dba1adcf675407977acc5f2622f5e0c0072822d00/docformatter-1.7.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b852834e31b25d6a493da6b3cfeb2364aeeb07f8c5788d3ace7f7808a0c58d8d",
"md5": "fc107057483b80f4fa0c815bb759edb3",
"sha256": "5e1897e316016debf3fdee3e0515e54faaaef32ef84efbd2fbbb03bf9198238c"
},
"downloads": -1,
"filename": "docformatter-1.7.4.tar.gz",
"has_sig": false,
"md5_digest": "fc107057483b80f4fa0c815bb759edb3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 25898,
"upload_time": "2023-07-10T13:48:11",
"upload_time_iso_8601": "2023-07-10T13:48:11.195759Z",
"url": "https://files.pythonhosted.org/packages/b8/52/834e31b25d6a493da6b3cfeb2364aeeb07f8c5788d3ace7f7808a0c58d8d/docformatter-1.7.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-10 13:48:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PyCQA",
"github_project": "docformatter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "docformatter"
}
JSON
