From f196a92055df2ef7603ad777abfaa2989d4b6744 Mon Sep 17 00:00:00 2001 From: Lewis Haley Date: Fri, 17 Aug 2018 16:02:11 +0100 Subject: [PATCH] autodoc: add 'exclude-members' to user global options As the previous commit explains, it is now possible to specify arguments to the global options in config files. This means that we can now include the `exclude-members` option in this global configuration. Previously, there was no point including this option because it makes no sense without arguments. Including this option means users have the flexibility of explicitly including which special methods they want using (e.g.): :special-members: __init__, __iter__ or explicitly excluding which special-members (or other members) they want using (e.g.): :exclude-members: __weakref__, __hash__ --- doc/usage/extensions/autodoc.rst | 4 ++- sphinx/ext/autodoc/directive.py | 2 +- tests/test_autodoc.py | 52 ++++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 2 deletions(-) diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 285756149..2b2a5f3ac 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -341,7 +341,8 @@ 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'``, ``'show-inheritance'`` and ``'ignore-module-all'``. + ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'`` + and ``'exclude-members'``. 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. @@ -361,6 +362,7 @@ There are also new config values that you can set: 'member-order': 'bysource', 'special-members': '__init__', 'undoc-members': None, + 'exclude-members': '__weakref__' } Setting ``None`` is equivalent to giving the option name in the list format diff --git a/sphinx/ext/autodoc/directive.py b/sphinx/ext/autodoc/directive.py index aabf6b47d..34f7567d4 100644 --- a/sphinx/ext/autodoc/directive.py +++ b/sphinx/ext/autodoc/directive.py @@ -31,7 +31,7 @@ logger = logging.getLogger(__name__) # common option names for autodoc directives AUTODOC_DEFAULT_OPTIONS = ['members', 'undoc-members', 'inherited-members', 'show-inheritance', 'private-members', 'special-members', - 'ignore-module-all'] + 'ignore-module-all', 'exclude-members'] class DummyOptionSpec(object): diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index a559fb164..0cd543ad7 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -1484,6 +1484,32 @@ def test_autodoc_default_flags__with_flags(app): assert ' .. py:attribute:: CustomIter.__weakref__' in actual assert ' list of weak references to the object (if defined)' in actual + # :exclude-members: None - has no effect. Unlike :members:, + # :special-members:, etc. where None == "include all", here None means + # "no/false/off". + app.config.autodoc_default_flags = { + 'members': None, + 'exclude-members': None, + } + actual = do_autodoc(app, 'class', 'target.EnumCls') + assert ' .. py:attribute:: EnumCls.val1' in actual + assert ' .. py:attribute:: EnumCls.val4' not in actual + app.config.autodoc_default_flags = { + 'members': None, + 'special-members': None, + 'exclude-members': None, + } + actual = do_autodoc(app, 'class', 'target.CustomIter') + assert ' .. py:method:: CustomIter.__init__()' in actual + assert ' Create a new `CustomIter`.' in actual + assert ' .. py:method:: CustomIter.__iter__()' in actual + assert ' Iterate squares of each value.' in actual + if not IS_PYPY: + assert ' .. py:attribute:: CustomIter.__weakref__' in actual + assert ' list of weak references to the object (if defined)' in actual + assert ' .. py:method:: CustomIter.snafucate()' in actual + assert ' Makes this snafucated.' in actual + @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_autodoc_default_flags__with_values(app): @@ -1509,3 +1535,29 @@ def test_autodoc_default_flags__with_values(app): if not IS_PYPY: assert ' .. py:attribute:: CustomIter.__weakref__' not in actual assert ' list of weak references to the object (if defined)' not in actual + + # with :exclude-members: + app.config.autodoc_default_flags = { + 'members': None, + 'exclude-members': 'val1' + } + actual = do_autodoc(app, 'class', 'target.EnumCls') + assert ' .. py:attribute:: EnumCls.val1' not in actual + assert ' .. py:attribute:: EnumCls.val2' in actual + assert ' .. py:attribute:: EnumCls.val3' in actual + assert ' .. py:attribute:: EnumCls.val4' not in actual + app.config.autodoc_default_flags = { + 'members': None, + 'special-members': None, + 'exclude-members': '__weakref__,snafucate', + } + actual = do_autodoc(app, 'class', 'target.CustomIter') + assert ' .. py:method:: CustomIter.__init__()' in actual + assert ' Create a new `CustomIter`.' in actual + assert ' .. py:method:: CustomIter.__iter__()' in actual + assert ' Iterate squares of each value.' in actual + if not IS_PYPY: + assert ' .. py:attribute:: CustomIter.__weakref__' not in actual + assert ' list of weak references to the object (if defined)' not in actual + assert ' .. py:method:: CustomIter.snafucate()' not in actual + assert ' Makes this snafucated.' not in actual