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

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

View File

@ -50,6 +50,7 @@ Features added
* #3160: html: Use ``<kdb>`` to represent ``:kbd:`` role
* #4212: autosummary: catch all exceptions when importing modules
* #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

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,
those whose name doesn't start with ``_``).
For modules, ``__all__`` will be respected when looking for members; the
order of the members will also be the order in ``__all__``.
For modules, ``__all__`` will be respected when looking for members unless
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
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
applied to all autodoc directives. The supported flags are ``'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
form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.

View File

@ -898,7 +898,7 @@ class ModuleDocumenter(Documenter):
'platform': identity, 'deprecated': bool_option,
'member-order': identity, 'exclude-members': members_set_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]
@classmethod
@ -940,7 +940,8 @@ class ModuleDocumenter(Documenter):
def get_object_members(self, want_all):
# type: (bool) -> Tuple[bool, List[Tuple[unicode, object]]]
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
# documenting imported objects
return True, safe_getmembers(self.object)
@ -1528,7 +1529,7 @@ class AutoDirective(Directive):
# flags that can be given in autodoc_default_flags
_default_flags = set([
'members', 'undoc-members', 'inherited-members', 'show-inheritance',
'private-members', 'special-members',
'private-members', 'special-members', 'ignore-module-all'
])
# standard docutils directive settings

View File

@ -64,6 +64,7 @@ def setup_test():
members = [],
member_order = 'alphabetic',
exclude_members = set(),
ignore_module_all = False,
)
directive = Struct(
@ -736,6 +737,12 @@ def test_generate():
else:
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
options.members = []
options.noindex = True