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

Merge pull request #2452 from mausr/stable

Browse Source 
Fix #2374: Init method inclusion.

Looks great! Thank you for your contribution!
This commit is contained in:
Rob Ruana 2016-05-01 16:41:53 -07:00
commit 683ad9a4c1
1 changed files with 30 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -33,6 +33,7 @@ class Config(object):
# Napoleon settings # Napoleon settings
napoleon_google_docstring = True napoleon_google_docstring = True
napoleon_numpy_docstring = True napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = False napoleon_include_special_with_doc = False
napoleon_use_admonition_for_examples = False napoleon_use_admonition_for_examples = False
@ -56,6 +57,21 @@ class Config(object):
napoleon_numpy_docstring : bool, defaults to True napoleon_numpy_docstring : bool, defaults to True
True to parse `NumPy style`_ docstrings. False to disable support True to parse `NumPy style`_ docstrings. False to disable support
for NumPy style docstrings. for NumPy style docstrings.
napoleon_include_init_with_doc : bool, defaults to False
True to include init methods (i.e. ``__init___``) with
docstrings in the documentation. False to fall back to Sphinx's
default behavior.
**If True**::
def __init__(self):
\"\"\"
This will be included in the docs because it has a docstring
\"\"\"
def __init__(self):
# This will NOT be included in the docs
napoleon_include_private_with_doc : bool, defaults to False napoleon_include_private_with_doc : bool, defaults to False
True to include private members (like ``_membername``) with docstrings True to include private members (like ``_membername``) with docstrings
in the documentation. False to fall back to Sphinx's default behavior. in the documentation. False to fall back to Sphinx's default behavior.
@ -223,6 +239,7 @@ class Config(object):
_config_values = { _config_values = {
'napoleon_google_docstring': (True, 'env'), 'napoleon_google_docstring': (True, 'env'),
'napoleon_numpy_docstring': (True, 'env'), 'napoleon_numpy_docstring': (True, 'env'),
'napoleon_include_init_with_doc': (False, 'env'),
'napoleon_include_private_with_doc': (False, 'env'), 'napoleon_include_private_with_doc': (False, 'env'),
'napoleon_include_special_with_doc': (False, 'env'), 'napoleon_include_special_with_doc': (False, 'env'),
'napoleon_use_admonition_for_examples': (False, 'env'), 'napoleon_use_admonition_for_examples': (False, 'env'),
@ -346,8 +363,10 @@ def _skip_member(app, what, name, obj, skip, options):
"""Determine if private and special class members are included in docs. """Determine if private and special class members are included in docs.
The following settings in conf.py determine if private and special class The following settings in conf.py determine if private and special class
members are included in the generated documentation: members or init methods are included in the generated documentation:
* ``napoleon_include_init_with_doc`` --
include init methods if they have docstrings
* ``napoleon_include_private_with_doc`` -- * ``napoleon_include_private_with_doc`` --
include private members if they have docstrings include private members if they have docstrings
* ``napoleon_include_special_with_doc`` -- * ``napoleon_include_special_with_doc`` --
@ -384,7 +403,7 @@ def _skip_member(app, what, name, obj, skip, options):
""" """
has_doc = getattr(obj, '__doc__', False) has_doc = getattr(obj, '__doc__', False)
is_member = (what == 'class' or what == 'exception' or what == 'module') is_member = (what == 'class' or what == 'exception' or what == 'module')
if name != '__weakref__' and name != '__init__' and has_doc and is_member: if name != '__weakref__' and has_doc and is_member:
cls_is_owner = False cls_is_owner = False
if what == 'class' or what == 'exception': if what == 'class' or what == 'exception':
if PY2: if PY2:
@ -417,10 +436,16 @@ def _skip_member(app, what, name, obj, skip, options):
cls_is_owner = True cls_is_owner = True
if what == 'module' or cls_is_owner: if what == 'module' or cls_is_owner:
is_special = name.startswith('__') and name.endswith('__') is_init = (name == '__init__')
is_private = not is_special and name.startswith('_') is_special = (not is_init and name.startswith('__') and
name.endswith('__'))
is_private = (not is_init and not is_special and
name.startswith('_'))
inc_init = app.config.napoleon_include_init_with_doc
inc_special = app.config.napoleon_include_special_with_doc inc_special = app.config.napoleon_include_special_with_doc
inc_private = app.config.napoleon_include_private_with_doc inc_private = app.config.napoleon_include_private_with_doc
if (is_special and inc_special) or (is_private and inc_private): if ((is_special and inc_special) or
(is_private and inc_private) or
(is_init and inc_init)):
return False return False
return skip return skip