From 63fbb819c74b36c87478e017cf35c01feba2bf50 Mon Sep 17 00:00:00 2001 From: Rob Ruana Date: Sun, 19 Jan 2014 13:43:54 -0500 Subject: [PATCH] Makes suggested changes before adding napoleon to sphinx --- CHANGES | 3 + doc/conf.py | 3 +- doc/ext/autodoc.rst | 10 ++ doc/ext/napoleon.rst | 56 ++++---- sphinx/ext/napoleon/__init__.py | 220 ++++++++++++++++---------------- tests/root/conf.py | 2 +- 6 files changed, 160 insertions(+), 134 deletions(-) diff --git a/CHANGES b/CHANGES index 402487b2f..31b4f04d3 100644 --- a/CHANGES +++ b/CHANGES @@ -36,6 +36,9 @@ New features * Prompt for the document language in sphinx-quickstart. +* Added ``sphinx.ext.napoleon`` extension for NumPy and Google style docstring + support. + Bugs fixed ---------- diff --git a/doc/conf.py b/doc/conf.py index b6515a38d..9932c8ed3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -7,8 +7,7 @@ import sphinx extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', - 'sphinx.ext.autosummary', 'sphinx.ext.extlinks', - 'sphinx.ext.napoleon'] + 'sphinx.ext.autosummary', 'sphinx.ext.extlinks'] master_doc = 'contents' templates_path = ['_templates'] diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 94b054233..38d7700e3 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -26,6 +26,16 @@ hand-written documentation, this technique eases the pain of having to maintain two locations for documentation, while at the same time avoiding auto-generated-looking pure API documentation. +If you prefer `NumPy`_ or `Google`_ style docstrings over reStructuredText, +you can also enable the :mod:`napoleon ` extension. +:mod:`napoleon ` is a preprocessor that converts your +docstrings to correct reStructuredText before :mod:`autodoc` processes them. + +.. _Google: + http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments +.. _NumPy: + https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt + :mod:`autodoc` provides several directives that are versions of the usual :rst:dir:`py:module`, :rst:dir:`py:class` and so forth. On parsing time, they import the corresponding module and extract the docstring of the given objects, diff --git a/doc/ext/napoleon.rst b/doc/ext/napoleon.rst index fde23c7b5..32deecb83 100644 --- a/doc/ext/napoleon.rst +++ b/doc/ext/napoleon.rst @@ -38,7 +38,7 @@ according to the `Google Python Style Guide`_:: Much more legible, no? -Napoleon is a `Sphinx extension`_ that allows you to write readable API +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`_. @@ -46,7 +46,6 @@ documentation in your source code. Napoleon understands both `NumPy`_ and .. _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: @@ -74,16 +73,14 @@ Getting Started Docstrings ---------- -Napoleon interprets every docstring that `Sphinx autodoc`_ can find, -including docstrings on: ``modules``, ``classes``, ``attributes``, +Napoleon interprets every docstring that :mod:`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: @@ -210,17 +207,21 @@ enabled in `conf.py`:: -**napoleon_google_docstring** : bool, defaults to True +.. confval:: napoleon_google_docstring + True to parse `Google style`_ docstrings. False to disable support - for Google style docstrings. + for Google style docstrings. *Defaults to True.* + +.. confval:: napoleon_numpy_docstring -**napoleon_numpy_docstring** : bool, defaults to True True to parse `NumPy style`_ docstrings. False to disable support - for NumPy style docstrings. + for NumPy style docstrings. *Defaults to True.* + +.. confval:: napoleon_include_private_with_doc -**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. + *Defaults to False.* **If True**:: @@ -234,10 +235,11 @@ enabled in `conf.py`:: # This will NOT be included in the docs pass -**napoleon_include_special_with_doc** : bool, defaults to True +.. confval:: napoleon_include_special_with_doc + True to include special members (like ``__membername__``) with docstrings in the documentation. False to fall back to Sphinx's - default behavior. + default behavior. *Defaults to True.* **If True**:: @@ -251,11 +253,12 @@ enabled in `conf.py`:: # This will NOT be included in the docs return unicode(self.__class__.__name__) -**napoleon_use_admonition_for_examples** : bool, defaults to False +.. confval:: napoleon_use_admonition_for_examples + 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. + theme is used. *Defaults to False.* This `NumPy style`_ snippet will be converted as follows:: @@ -275,9 +278,10 @@ enabled in `conf.py`:: This is just a quick example -**napoleon_use_admonition_for_notes** : bool, defaults to False +.. confval:: napoleon_use_admonition_for_notes + True to use the ``.. admonition::`` directive for **Notes** sections. - False to use the ``.. rubric::`` directive instead. + False to use the ``.. rubric::`` directive instead. *Defaults to False.* .. note:: The singular **Note** section will always be converted to a ``.. note::`` directive. @@ -286,17 +290,20 @@ enabled in `conf.py`:: :attr:`napoleon_use_admonition_for_examples` -**napoleon_use_admonition_for_references** : bool, defaults to False +.. confval:: napoleon_use_admonition_for_references + True to use the ``.. admonition::`` directive for **References** sections. False to use the ``.. rubric::`` directive instead. + *Defaults to False.* .. seealso:: :attr:`napoleon_use_admonition_for_examples` -**napoleon_use_ivar** : bool, defaults to False +.. confval:: napoleon_use_ivar + True to use the ``:ivar:`` role for instance variables. False to use - the ``.. attribute::`` directive instead. + the ``.. attribute::`` directive instead. *Defaults to False.* This `NumPy style`_ snippet will be converted as follows:: @@ -317,9 +324,11 @@ enabled in `conf.py`:: Description of `attr1` -**napoleon_use_param** : bool, defaults to False +.. confval:: napoleon_use_param + True to use a ``:param:`` role for each function parameter. False to use a single ``:parameters:`` role for all the parameters. + *Defaults to False.* This `NumPy style`_ snippet will be converted as follows:: @@ -344,9 +353,10 @@ enabled in `conf.py`:: * **arg2** (*int, optional*) -- Description of `arg2`, defaults to 0 -**napoleon_use_rtype** : bool, defaults to False +.. confval:: napoleon_use_rtype + True to use the ``:rtype:`` role for the return type. False to output - the return type inline with the description. + the return type inline with the description. *Defaults to False.* This `NumPy style`_ snippet will be converted as follows:: diff --git a/sphinx/ext/napoleon/__init__.py b/sphinx/ext/napoleon/__init__.py index 168ac5741..d3b6f754f 100644 --- a/sphinx/ext/napoleon/__init__.py +++ b/sphinx/ext/napoleon/__init__.py @@ -43,157 +43,161 @@ class Config(object): .. _NumPy style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt + Attributes + ---------- + 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**:: - **napoleon_google_docstring** : bool, defaults to True - True to parse `Google style`_ docstrings. False to disable support - for Google style docstrings. + def _included(self): + \"\"\" + This will be included in the docs because it has a docstring + \"\"\" + pass - **napoleon_numpy_docstring** : bool, defaults to True - True to parse `NumPy style`_ docstrings. False to disable support - for NumPy style docstrings. + def _skipped(self): + # This will NOT be included in the docs + pass - **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. + 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**:: + **If True**:: - def _included(self): - \"\"\" - This will be included in the docs because it has a docstring - \"\"\" - pass + def __str__(self): + \"\"\" + This will be included in the docs because it has a docstring + \"\"\" + return unicode(self).encode('utf-8') - def _skipped(self): - # This will NOT be included in the docs - pass + def __unicode__(self): + # This will NOT be included in the docs + return unicode(self.__class__.__name__) - **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. + 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. - **If True**:: + This `NumPy style`_ snippet will be converted as follows:: - def __str__(self): - \"\"\" - This will be included in the docs because it has a docstring - \"\"\" - return unicode(self).encode('utf-8') + Example + ------- + This is just a quick example - def __unicode__(self): - # This will NOT be included in the docs - return unicode(self.__class__.__name__) + **If True**:: - **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. + .. admonition:: Example - This `NumPy style`_ snippet will be converted as follows:: + This is just a quick example - Example - ------- - This is just a quick example + **If False**:: - **If True**:: + .. rubric:: Example - .. admonition:: Example + This is just a quick 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. - **If False**:: + Note + ---- + The singular **Note** section will always be converted to a + ``.. note::`` directive. - .. rubric:: Example + See Also + -------- + :attr:`napoleon_use_admonition_for_examples` - This is just a quick example + 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. - **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. + See Also + -------- + :attr:`napoleon_use_admonition_for_examples` - .. note:: The singular **Note** section will always be converted to a - ``.. note::`` directive. + napoleon_use_ivar : bool, defaults to False + True to use the ``:ivar:`` role for instance variables. False to use + the ``.. attribute::`` directive instead. - .. seealso:: :attr:`napoleon_use_admonition_for_examples` + This `NumPy style`_ snippet will be converted as follows:: - **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. + Attributes + ---------- + attr1 : int + Description of `attr1` - .. seealso:: :attr:`napoleon_use_admonition_for_examples` + **If True**:: - **napoleon_use_ivar** : bool, defaults to False - True to use the ``:ivar:`` role for instance variables. False to use - the ``.. attribute::`` directive instead. + :ivar attr1: Description of `attr1` + :vartype attr1: int - This `NumPy style`_ snippet will be converted as follows:: + **If False**:: + + .. attribute:: attr1 + :annotation: int - Attributes - ---------- - attr1 : int Description of `attr1` - **If True**:: + 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. - :ivar attr1: Description of `attr1` - :vartype attr1: int + This `NumPy style`_ snippet will be converted as follows:: - **If False**:: + Parameters + ---------- + arg1 : str + Description of `arg1` + arg2 : int, optional + Description of `arg2`, defaults to 0 - .. attribute:: attr1 - :annotation: int + **If True**:: - Description of `attr1` + :param arg1: Description of `arg1` + :type arg1: str + :param arg2: Description of `arg2`, defaults to 0 + :type arg2: int, optional - **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. + **If False**:: - This `NumPy style`_ snippet will be converted as follows:: + :parameters: * **arg1** (*str*) -- + Description of `arg1` + * **arg2** (*int, optional*) -- + Description of `arg2`, defaults to 0 - 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. - **If True**:: + This `NumPy style`_ snippet will be converted as follows:: - :param arg1: Description of `arg1` - :type arg1: str - :param arg2: Description of `arg2`, defaults to 0 - :type arg2: int, optional + Returns + ------- + bool + True if successful, False otherwise - **If False**:: + **If True**:: - :parameters: * **arg1** (*str*) -- - Description of `arg1` - * **arg2** (*int, optional*) -- - Description of `arg2`, defaults to 0 + :returns: True if successful, False otherwise + :rtype: bool - **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. + **If False**:: - 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 + :returns: *bool* -- True if successful, False otherwise """ _config_values = { diff --git a/tests/root/conf.py b/tests/root/conf.py index af984e5ea..f0d40148b 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -8,7 +8,7 @@ sys.path.append(os.path.abspath('..')) extensions = ['sphinx.ext.autodoc', 'sphinx.ext.jsmath', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.autosummary', 'sphinx.ext.doctest', 'sphinx.ext.extlinks', - 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'ext'] + 'sphinx.ext.viewcode', 'ext'] jsmath_path = 'dummy.js'