IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Makes suggested changes before adding napoleon to sphinx

Browse Source
This commit is contained in:
Rob Ruana 2014-01-19 13:43:54 -05:00
parent 4c782604ed
commit 63fbb819c7
6 changed files with 160 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGES
View File

@ -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
----------

3
doc/conf.py
View File

@ -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']

10
doc/ext/autodoc.rst
View File

@ -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 <sphinx.ext.napoleon>` extension.
:mod:`napoleon <sphinx.ext.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,

56
doc/ext/napoleon.rst
View File

@ -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 <sphinx.ext.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::

220
sphinx/ext/napoleon/__init__.py
View File

@ -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 = {

2
tests/root/conf.py
View File

@ -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'