Napoleon - *Marching toward legible docstrings*
===============================================
.. note:: As of Sphinx 1.3, the napoleon extension will come packaged with
Sphinx under `sphinx.ext.napoleon`. The `sphinxcontrib.napoleon` extension
will continue to work with Sphinx <= 1.2.
Are you tired of writing docstrings that look like this::
:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage
`ReStructuredText`_ is great, but it creates visually dense, hard to read
`docstrings`_. Compare the jumble above to the same thing rewritten
according to the `Google Python Style Guide`_::
Args:
path (str): The path of the file to wrap
field_storage (FileStorage): The :class:`FileStorage` instance to wrap
temporary (bool): Whether or not to delete the file when the File
instance is destructed
Returns:
BufferedFileStorage: A buffered writable file descriptor
Much more legible, no?
Napoleon is a `Sphinx extension`_ that enables Sphinx to parse both `NumPy`_
and `Google`_ style docstrings - the style recommended by `Khan Academy`_.
Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style
docstrings and converts them to reStructuredText before Sphinx attempts to
parse them. This happens in an intermediate step while Sphinx is processing
the documentation, so it doesn't modify any of the docstrings in your actual
source code files.
.. _ReStructuredText: http://docutils.sourceforge.net/rst.html
.. _docstrings: http://www.python.org/dev/peps/pep-0287/
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
.. _Sphinx extension: http://sphinx-doc.org/extensions.html
.. _Google:
http://google.github.io/styleguide/pyguide.html#Comments
.. _NumPy:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _Khan Academy:
https://sites.google.com/a/khanacademy.org/forge/for-developers/styleguide/python#TOC-Docstrings
Getting Started
---------------
1. Install the napoleon extension::
$ pip install sphinxcontrib-napoleon
2. After `setting up Sphinx`_ to build your docs, enable napoleon in the
Sphinx `conf.py` file::
# conf.py
# Add napoleon to the extensions list
extensions = ['sphinxcontrib.napoleon']
2. Use `sphinx-apidoc` to build your API documentation::
$ sphinx-apidoc -f -o docs/source projectdir
.. _setting up Sphinx: http://sphinx-doc.org/tutorial.html
Docstrings
----------
Napoleon interprets every docstring that `Sphinx autodoc`_ can find,
including docstrings on: ``modules``, ``classes``, ``attributes``,
``methods``, ``functions``, and ``variables``. Inside each docstring,
specially formatted `Sections`_ are parsed and converted to
reStructuredText.
All standard reStructuredText formatting still works as expected.
.. _Sphinx autodoc: http://sphinx-doc.org/ext/autodoc.html
.. _Sections:
Docstring Sections
------------------
All of the following section headers are supported:
* ``Args`` *(alias of Parameters)*
* ``Arguments`` *(alias of Parameters)*
* ``Attributes``
* ``Example``
* ``Examples``
* ``Keyword Args`` *(alias of Keyword Arguments)*
* ``Keyword Arguments``
* ``Methods``
* ``Note``
* ``Notes``
* ``Other Parameters``
* ``Parameters``
* ``Return`` *(alias of Returns)*
* ``Returns``
* ``Raises``
* ``References``
* ``See Also``
* ``Warning``
* ``Warnings`` *(alias of Warning)*
* ``Warns``
* ``Yield`` *(alias of Yields)*
* ``Yields``
Google vs NumPy
---------------
Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The
main difference between the two styles is that Google uses indention to
separate sections, whereas NumPy uses underlines.
Google style::
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return True
NumPy style::
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
"""
return True
NumPy style tends to require more vertical space, whereas Google style
tends to use more horizontal space. Google style tends to be easier to
read for short and simple docstrings, whereas NumPy style tends be easier
to read for long and in-depth docstrings.
The `Khan Academy`_ recommends using Google style.
The choice between styles is largely aesthetic, but the two styles should
not be mixed. Choose one style for your project and be consistent with it.
For full documentation see https://sphinxcontrib-napoleon.readthedocs.io
Raw data
{
"_id": null,
"home_page": "https://sphinxcontrib-napoleon.readthedocs.io",
"name": "sphinxcontrib-napoleon",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Rob Ruana",
"author_email": "rob@robruana.com",
"download_url": "https://files.pythonhosted.org/packages/fa/eb/ad89500f4cee83187596e07f43ad561f293e8e6e96996005c3319653b89f/sphinxcontrib-napoleon-0.7.tar.gz",
"platform": "any",
"description": "Napoleon - *Marching toward legible docstrings*\n===============================================\n\n.. note:: As of Sphinx 1.3, the napoleon extension will come packaged with\n Sphinx under `sphinx.ext.napoleon`. The `sphinxcontrib.napoleon` extension\n will continue to work with Sphinx <= 1.2.\n\nAre you tired of writing docstrings that look like this::\n\n :param path: The path of the file to wrap\n :type path: str\n :param field_storage: The :class:`FileStorage` instance to wrap\n :type field_storage: FileStorage\n :param temporary: Whether or not to delete the file when the File\n instance is destructed\n :type temporary: bool\n :returns: A buffered writable file descriptor\n :rtype: BufferedFileStorage\n\n`ReStructuredText`_ is great, but it creates visually dense, hard to read\n`docstrings`_. Compare the jumble above to the same thing rewritten\naccording to the `Google Python Style Guide`_::\n\n Args:\n path (str): The path of the file to wrap\n field_storage (FileStorage): The :class:`FileStorage` instance to wrap\n temporary (bool): Whether or not to delete the file when the File\n instance is destructed\n\n Returns:\n BufferedFileStorage: A buffered writable file descriptor\n\nMuch more legible, no?\n\nNapoleon is a `Sphinx extension`_ that enables Sphinx to parse both `NumPy`_\nand `Google`_ style docstrings - the style recommended by `Khan Academy`_.\n\nNapoleon is a pre-processor that parses `NumPy`_ and `Google`_ style\ndocstrings and converts them to reStructuredText before Sphinx attempts to\nparse them. This happens in an intermediate step while Sphinx is processing\nthe documentation, so it doesn't modify any of the docstrings in your actual\nsource code files.\n\n.. _ReStructuredText: http://docutils.sourceforge.net/rst.html\n.. _docstrings: http://www.python.org/dev/peps/pep-0287/\n.. _Google Python Style Guide:\n http://google.github.io/styleguide/pyguide.html\n.. _Sphinx extension: http://sphinx-doc.org/extensions.html\n.. _Google:\n http://google.github.io/styleguide/pyguide.html#Comments\n.. _NumPy:\n https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt\n.. _Khan Academy:\n https://sites.google.com/a/khanacademy.org/forge/for-developers/styleguide/python#TOC-Docstrings\n\nGetting Started\n---------------\n\n1. Install the napoleon extension::\n\n $ pip install sphinxcontrib-napoleon\n\n2. After `setting up Sphinx`_ to build your docs, enable napoleon in the\n Sphinx `conf.py` file::\n\n # conf.py\n\n # Add napoleon to the extensions list\n extensions = ['sphinxcontrib.napoleon']\n\n2. Use `sphinx-apidoc` to build your API documentation::\n\n $ sphinx-apidoc -f -o docs/source projectdir\n\n.. _setting up Sphinx: http://sphinx-doc.org/tutorial.html\n\nDocstrings\n----------\n\nNapoleon interprets every docstring that `Sphinx autodoc`_ can find,\nincluding docstrings on: ``modules``, ``classes``, ``attributes``,\n``methods``, ``functions``, and ``variables``. Inside each docstring,\nspecially formatted `Sections`_ are parsed and converted to\nreStructuredText.\n\nAll standard reStructuredText formatting still works as expected.\n\n.. _Sphinx autodoc: http://sphinx-doc.org/ext/autodoc.html\n\n\n.. _Sections:\n\nDocstring Sections\n------------------\n\nAll of the following section headers are supported:\n\n * ``Args`` *(alias of Parameters)*\n * ``Arguments`` *(alias of Parameters)*\n * ``Attributes``\n * ``Example``\n * ``Examples``\n * ``Keyword Args`` *(alias of Keyword Arguments)*\n * ``Keyword Arguments``\n * ``Methods``\n * ``Note``\n * ``Notes``\n * ``Other Parameters``\n * ``Parameters``\n * ``Return`` *(alias of Returns)*\n * ``Returns``\n * ``Raises``\n * ``References``\n * ``See Also``\n * ``Warning``\n * ``Warnings`` *(alias of Warning)*\n * ``Warns``\n * ``Yield`` *(alias of Yields)*\n * ``Yields``\n\nGoogle vs NumPy\n---------------\n\nNapoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The\nmain difference between the two styles is that Google uses indention to\nseparate sections, whereas NumPy uses underlines.\n\nGoogle style::\n\n def func(arg1, arg2):\n \"\"\"Summary line.\n\n Extended description of function.\n\n Args:\n arg1 (int): Description of arg1\n arg2 (str): Description of arg2\n\n Returns:\n bool: Description of return value\n\n \"\"\"\n return True\n\nNumPy style::\n\n def func(arg1, arg2):\n \"\"\"Summary line.\n\n Extended description of function.\n\n Parameters\n ----------\n arg1 : int\n Description of arg1\n arg2 : str\n Description of arg2\n\n Returns\n -------\n bool\n Description of return value\n\n \"\"\"\n return True\n\nNumPy style tends to require more vertical space, whereas Google style\ntends to use more horizontal space. Google style tends to be easier to\nread for short and simple docstrings, whereas NumPy style tends be easier\nto read for long and in-depth docstrings.\n\nThe `Khan Academy`_ recommends using Google style.\n\nThe choice between styles is largely aesthetic, but the two styles should\nnot be mixed. Choose one style for your project and be consistent with it.\n\n\nFor full documentation see https://sphinxcontrib-napoleon.readthedocs.io\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Sphinx \"napoleon\" extension.",
"version": "0.7",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "4350fac147484d83fd0a754cadd2968a",
"sha256": "711e41a3974bdf110a484aec4c1a556799eb0b3f3b897521a018ad7e2db13fef"
},
"downloads": -1,
"filename": "sphinxcontrib_napoleon-0.7-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "4350fac147484d83fd0a754cadd2968a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 17151,
"upload_time": "2018-09-23T14:16:45",
"upload_time_iso_8601": "2018-09-23T14:16:45.548456Z",
"url": "https://files.pythonhosted.org/packages/75/f2/6b7627dfe7b4e418e295e254bb15c3a6455f11f8c0ad0d43113f678049c3/sphinxcontrib_napoleon-0.7-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "080555f8bcdf5de9819798c24bdd02f8",
"sha256": "407382beed396e9f2d7f3043fad6afda95719204a1e1a231ac865f40abcbfcf8"
},
"downloads": -1,
"filename": "sphinxcontrib-napoleon-0.7.tar.gz",
"has_sig": false,
"md5_digest": "080555f8bcdf5de9819798c24bdd02f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21232,
"upload_time": "2018-09-23T14:16:47",
"upload_time_iso_8601": "2018-09-23T14:16:47.272698Z",
"url": "https://files.pythonhosted.org/packages/fa/eb/ad89500f4cee83187596e07f43ad561f293e8e6e96996005c3319653b89f/sphinxcontrib-napoleon-0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2018-09-23 14:16:47",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "sphinxcontrib-napoleon"
}
JSON