Merges napoleon extension into mainline sphinx

doc/ext/napoleon.rst

@@ -0,0 +1,365 @@
+:mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. module:: sphinx.ext.napoleon
+   :synopsis: Support for NumPy and Google style docstrings
+
+.. moduleauthor:: Rob Ruana
+
+.. versionadded:: 1.3
+
+Napoleon - *Marching toward legible docstrings*
+===============================================
+
+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 allows you to write readable API
+documentation in your source code. Napoleon understands both `NumPy`_ and
+`Google`_ style docstrings - the style recommended by `Khan Academy`_.
+
+.. _ReStructuredText: http://docutils.sourceforge.net/rst.html
+.. _docstrings: http://www.python.org/dev/peps/pep-0287/
+.. _Google Python Style Guide:
+   http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
+.. _Sphinx extension: http://sphinx-doc.org/extensions.html
+.. _Google:
+   http://google-styleguide.googlecode.com/svn/trunk/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. After `setting up Sphinx`_ to build your docs, enable napoleon in the
+   Sphinx `conf.py` file::
+
+       # conf.py
+
+       # Add autodoc and napoleon to the extensions list
+       extensions = ['sphinx.ext.autodoc', 'sphinx.ext.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``
+    * ``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.
+
+.. seealso::
+
+   For complete examples:
+
+   * :ref:`example_google`
+   * :ref:`example_numpy`
+
+
+Configuration
+=============
+
+Listed below are all the settings used by napoleon and their default
+values. These settings can be changed in the Sphinx `conf.py` file. Make
+sure that both "sphinx.ext.autodoc" and "sphinx.ext.napoleon" are
+enabled in `conf.py`::
+
+    # conf.py
+
+    # Add any Sphinx extension module names here, as strings
+    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+
+    # Napoleon settings
+    napoleon_google_docstring = True
+    napoleon_numpy_docstring = True
+    napoleon_include_private_with_doc = False
+    napoleon_include_special_with_doc = True
+    napoleon_use_admonition_for_examples = False
+    napoleon_use_admonition_for_notes = False
+    napoleon_use_admonition_for_references = False
+    napoleon_use_ivar = False
+    napoleon_use_param = False
+    napoleon_use_rtype = False
+
+.. _Google style:
+   http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
+.. _NumPy style:
+   https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+
+
+
+**napoleon_google_docstring** : bool, defaults to True
+   True to parse `Google style`_ docstrings. False to disable support
+   for Google style docstrings.
+
+**napoleon_numpy_docstring** : bool, defaults to True
+   True to parse `NumPy style`_ docstrings. False to disable support
+   for NumPy style docstrings.
+
+**napoleon_include_private_with_doc** : bool, defaults to False
+   True to include private members (like ``_membername``) with docstrings
+   in the documentation. False to fall back to Sphinx's default behavior.
+
+   **If True**::
+
+       def _included(self):
+           """
+           This will be included in the docs because it has a docstring
+           """
+           pass
+
+       def _skipped(self):
+           # This will NOT be included in the docs
+           pass
+
+**napoleon_include_special_with_doc** : bool, defaults to True
+   True to include special members (like ``__membername__``) with
+   docstrings in the documentation. False to fall back to Sphinx's
+   default behavior.
+
+   **If True**::
+
+       def __str__(self):
+           """
+           This will be included in the docs because it has a docstring
+           """
+           return unicode(self).encode('utf-8')
+
+       def __unicode__(self):
+           # This will NOT be included in the docs
+           return unicode(self.__class__.__name__)
+
+**napoleon_use_admonition_for_examples** : bool, defaults to False
+   True to use the ``.. admonition::`` directive for the **Example** and
+   **Examples** sections. False to use the ``.. rubric::`` directive
+   instead. One may look better than the other depending on what HTML
+   theme is used.
+
+   This `NumPy style`_ snippet will be converted as follows::
+
+       Example
+       -------
+       This is just a quick example
+
+   **If True**::
+
+       .. admonition:: Example
+
+          This is just a quick example
+
+   **If False**::
+
+       .. rubric:: Example
+
+       This is just a quick example
+
+**napoleon_use_admonition_for_notes** : bool, defaults to False
+   True to use the ``.. admonition::`` directive for **Notes** sections.
+   False to use the ``.. rubric::`` directive instead.
+
+   .. note:: The singular **Note** section will always be converted to a
+      ``.. note::`` directive.
+
+   .. seealso::
+
+      :attr:`napoleon_use_admonition_for_examples`
+
+**napoleon_use_admonition_for_references** : bool, defaults to False
+   True to use the ``.. admonition::`` directive for **References**
+   sections. False to use the ``.. rubric::`` directive instead.
+
+   .. seealso::
+
+      :attr:`napoleon_use_admonition_for_examples`
+
+**napoleon_use_ivar** : bool, defaults to False
+   True to use the ``:ivar:`` role for instance variables. False to use
+   the ``.. attribute::`` directive instead.
+
+   This `NumPy style`_ snippet will be converted as follows::
+
+       Attributes
+       ----------
+       attr1 : int
+           Description of `attr1`
+
+   **If True**::
+
+       :ivar attr1: Description of `attr1`
+       :vartype attr1: int
+
+   **If False**::
+
+       .. attribute:: attr1
+          :annotation: int
+
+          Description of `attr1`
+
+**napoleon_use_param** : bool, defaults to False
+   True to use a ``:param:`` role for each function parameter. False to
+   use a single ``:parameters:`` role for all the parameters.
+
+   This `NumPy style`_ snippet will be converted as follows::
+
+       Parameters
+       ----------
+       arg1 : str
+           Description of `arg1`
+       arg2 : int, optional
+           Description of `arg2`, defaults to 0
+
+   **If True**::
+
+       :param arg1: Description of `arg1`
+       :type arg1: str
+       :param arg2: Description of `arg2`, defaults to 0
+       :type arg2: int, optional
+
+   **If False**::
+
+       :parameters: * **arg1** (*str*) --
+                      Description of `arg1`
+                    * **arg2** (*int, optional*) --
+                      Description of `arg2`, defaults to 0
+
+**napoleon_use_rtype** : bool, defaults to False
+   True to use the ``:rtype:`` role for the return type. False to output
+   the return type inline with the description.
+
+   This `NumPy style`_ snippet will be converted as follows::
+
+       Returns
+       -------
+       bool
+           True if successful, False otherwise
+
+   **If True**::
+
+       :returns: True if successful, False otherwise
+       :rtype: bool
+
+   **If False**::
+
+       :returns: *bool* -- True if successful, False otherwise