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

Closes #947: autodoc now supports ignore-module-all to ignore a module's __all__

Browse Source
This commit is contained in:
Kevin Keating 2017-12-20 15:07:33 -05:00
parent a95bc095c0
commit e932ff5ad2
4 changed files with 17 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGES
View File

@ -50,6 +50,7 @@ Features added
* #3160: html: Use ``<kdb>`` to represent ``:kbd:`` role * #3160: html: Use ``<kdb>`` to represent ``:kbd:`` role
* #4212: autosummary: catch all exceptions when importing modules * #4212: autosummary: catch all exceptions when importing modules
* #3991, #4080: Add :confval:`math_numfig` for equation numbering by section * #3991, #4080: Add :confval:`math_numfig` for equation numbering by section
* #947: autodoc now supports ignore-module-all to ignore a module's ``__all__``
Features removed Features removed

8
doc/ext/autodoc.rst
View File

@ -103,8 +103,10 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
will document all non-private member functions and properties (that is, will document all non-private member functions and properties (that is,
those whose name doesn't start with ``_``). those whose name doesn't start with ``_``).
For modules, ``__all__`` will be respected when looking for members; the For modules, ``__all__`` will be respected when looking for members unless
order of the members will also be the order in ``__all__``. you give the ``ignore-module-all`` flag option. Without
``ignore-module-all``, the order of the members will also be the order in
``__all__``.
You can also give an explicit list of members; only these will then be You can also give an explicit list of members; only these will then be
documented:: documented::
@ -339,7 +341,7 @@ There are also new config values that you can set:
This value is a list of autodoc directive flags that should be automatically This value is a list of autodoc directive flags that should be automatically
applied to all autodoc directives. The supported flags are ``'members'``, applied to all autodoc directives. The supported flags are ``'members'``,
``'undoc-members'``, ``'private-members'``, ``'special-members'``, ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
``'inherited-members'`` and ``'show-inheritance'``. ``'inherited-members'``, ``'show-inheritance'`` and ``'ignore-module-all'``.
If you set one of these flags in this config value, you can use a negated If you set one of these flags in this config value, you can use a negated
form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once. form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.

7
sphinx/ext/autodoc/__init__.py
View File

@ -898,7 +898,7 @@ class ModuleDocumenter(Documenter):
'platform': identity, 'deprecated': bool_option, 'platform': identity, 'deprecated': bool_option,
'member-order': identity, 'exclude-members': members_set_option, 'member-order': identity, 'exclude-members': members_set_option,
'private-members': bool_option, 'special-members': members_option, 'private-members': bool_option, 'special-members': members_option,
'imported-members': bool_option, 'imported-members': bool_option, 'ignore-module-all': bool_option
} # type: Dict[unicode, Callable] } # type: Dict[unicode, Callable]
@classmethod @classmethod
@ -940,7 +940,8 @@ class ModuleDocumenter(Documenter):
def get_object_members(self, want_all): def get_object_members(self, want_all):
# type: (bool) -> Tuple[bool, List[Tuple[unicode, object]]] # type: (bool) -> Tuple[bool, List[Tuple[unicode, object]]]
if want_all: if want_all:
if not hasattr(self.object, '__all__'): if (self.options.ignore_module_all or not
hasattr(self.object, '__all__')):
# for implicit module members, check __module__ to avoid # for implicit module members, check __module__ to avoid
# documenting imported objects # documenting imported objects
return True, safe_getmembers(self.object) return True, safe_getmembers(self.object)
@ -1528,7 +1529,7 @@ class AutoDirective(Directive):
# flags that can be given in autodoc_default_flags # flags that can be given in autodoc_default_flags
_default_flags = set([ _default_flags = set([
'members', 'undoc-members', 'inherited-members', 'show-inheritance', 'members', 'undoc-members', 'inherited-members', 'show-inheritance',
'private-members', 'special-members', 'private-members', 'special-members', 'ignore-module-all'
]) ])
# standard docutils directive settings # standard docutils directive settings

7
tests/test_autodoc.py
View File

@ -64,6 +64,7 @@ def setup_test():
members = [], members = [],
member_order = 'alphabetic', member_order = 'alphabetic',
exclude_members = set(), exclude_members = set(),
ignore_module_all = False,
) )
directive = Struct( directive = Struct(
@ -736,6 +737,12 @@ def test_generate():
else: else:
assert False, 'documented CustomEx which is not in __all__' assert False, 'documented CustomEx which is not in __all__'
# test ignore-module-all
options.ignore_module_all = True
assert_result_contains('.. py:class:: Class(arg)', 'module', 'test_autodoc')
assert_result_contains('.. py:exception:: CustomEx', 'module',
'test_autodoc')
# test noindex flag # test noindex flag
options.members = [] options.members = []
options.noindex = True options.noindex = True