diff --git a/CHANGES b/CHANGES index 8cef65071..b1b767863 100644 --- a/CHANGES +++ b/CHANGES @@ -65,6 +65,7 @@ Deprecated ---------- * :confval:`source_parsers` is deprecated +* :confval:`autodoc_default_flags` is deprecated * quickstart: ``--epub`` option becomes default, so it is deprecated * Drop function based directive support. For now, Sphinx only supports class based directives. @@ -210,7 +211,8 @@ Features added builder * #5273: doctest: Skip doctest conditionally * #5306: autodoc: emit a warning for invalid typehints -* #5215: autodoc: :confval:`autodoc_default_flags` accepts option values as dict +* #4075, #5215: autodoc: Add :confval:`autodoc_default_options` which accepts + option values as dict Bugs fixed ---------- diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 0fa4db260..6e8bdd41d 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -131,6 +131,11 @@ The following is a list of deprecated interface. - 4.0 - :meth:`~sphinx.application.Sphinx.add_js_file()` + * - :confval:`autodoc_default_flags` + - 1.8 + - 4.0 + - :confval:`autodoc_default_options` + * - ``sphinx.directives.other.VersionChanges`` - 1.8 - 3.0 diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 2b2a5f3ac..97ac51903 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -114,8 +114,17 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, .. autoclass:: Noodle :members: eat, slurp - * If you want to make the ``members`` option (or other flag options described - below) the default, see :confval:`autodoc_default_flags`. + * If you want to make the ``members`` option (or other options described + below) the default, see :confval:`autodoc_default_options`. + + .. tip:: + + You can use a negated form, :samp:`'no-{flag}'`, as an option of + autodoc directive, to disable it temporarily. For example:: + + .. automodule:: foo + :no-undoc-members: + * Members without docstrings will be left out, unless you give the ``undoc-members`` flag option:: @@ -344,35 +353,34 @@ There are also new config values that you can set: ``'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. - For example, if ``autodoc_default_flags`` is set to ``['members', - 'undoc-members']``, and you write a directive like this:: - - .. automodule:: foo - :no-undoc-members: - - the directive will be interpreted as if only ``:members:`` was given. - - You can also set `autodoc_default_flags` to a dictionary, mapping option - names to the values which can used in .rst files. For example:: - - autodoc_default_flags = { - 'members': 'var1, var2', - '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 - (i.e. it means "yes/true/on"). - .. versionadded:: 1.0 - .. versionchanged:: 1.8 + .. deprecated:: 1.8 - Specifying in dictionary format added. + Integrated into :confval:`autodoc_default_options`. + +.. confval:: autodoc_default_options + + The default options for autodoc directives. They are applied to all autodoc + directives automatically. It must be a dictionally which maps option names + to the values. For example:: + + autodoc_default_options = { + 'members': 'var1, var2', + '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 + (i.e. it means "yes/true/on"). + + The supported options are ``'members'``, ``'undoc-members'``, + ``'private-members'``, ``'special-members'``, ``'inherited-members'``, + ``'show-inheritance'``, ``'ignore-module-all'`` and ``'exclude-members'``. + + .. versionadded:: 1.8 .. confval:: autodoc_docstring_signature diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 4b585160a..41a6731d2 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -1532,33 +1532,24 @@ def autodoc_attrgetter(app, obj, name, *defargs): return safe_getattr(obj, name, *defargs) -def convert_autodoc_default_flags(app, config): +def merge_autodoc_default_flags(app, config): # type: (Sphinx, Config) -> None - """This converts the old list-of-flags (strings) to a dict of Nones.""" - if isinstance(config.autodoc_default_flags, dict): - # Already new-style + """This merges the autodoc_default_flags to autodoc_default_options.""" + if not config.autodoc_default_flags: return - elif not isinstance(config.autodoc_default_flags, list): - # Not old-style list - logger.error( - __("autodoc_default_flags is invalid type %r"), - config.autodoc_default_flags.__class__.__name__ - ) - return + logger.warning(__('autodoc_default_flags is now deprecated. ' + 'Please use autodoc_default_options instead.')) - autodoc_default_flags = {} # type: Dict[unicode, Any] for option in config.autodoc_default_flags: if isinstance(option, string_types): - autodoc_default_flags[option] = None + config.autodoc_default_options[option] = None else: logger.warning( __("Ignoring invalid option in autodoc_default_flags: %r"), option ) - config.autodoc_default_flags = autodoc_default_flags # type: ignore - def setup(app): # type: (Sphinx) -> Dict[unicode, Any] @@ -1573,7 +1564,8 @@ def setup(app): app.add_config_value('autoclass_content', 'class', True) app.add_config_value('autodoc_member_order', 'alphabetic', True) - app.add_config_value('autodoc_default_flags', {}, True, Any) + app.add_config_value('autodoc_default_flags', [], True) + app.add_config_value('autodoc_default_options', {}, True) app.add_config_value('autodoc_docstring_signature', True, True) app.add_config_value('autodoc_mock_imports', [], True) app.add_config_value('autodoc_warningiserror', True, True) @@ -1582,6 +1574,6 @@ def setup(app): app.add_event('autodoc-process-signature') app.add_event('autodoc-skip-member') - app.connect('config-inited', convert_autodoc_default_flags) + app.connect('config-inited', merge_autodoc_default_flags) return {'version': sphinx.__display_version__, 'parallel_read_safe': True} diff --git a/sphinx/ext/autodoc/directive.py b/sphinx/ext/autodoc/directive.py index 34f7567d4..3a3434fc8 100644 --- a/sphinx/ext/autodoc/directive.py +++ b/sphinx/ext/autodoc/directive.py @@ -67,8 +67,8 @@ def process_documenter_options(documenter, config, options): continue else: negated = options.pop('no-' + name, True) is None - if name in config.autodoc_default_flags and not negated: - options[name] = config.autodoc_default_flags[name] + if name in config.autodoc_default_options and not negated: + options[name] = config.autodoc_default_options[name] return Options(assemble_option_dict(options.items(), documenter.option_spec)) diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 767ab418e..c9a342f94 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -21,7 +21,7 @@ from six import PY3 from sphinx.ext.autodoc import ( AutoDirective, ModuleLevelDocumenter, cut_lines, between, ALL, - convert_autodoc_default_flags + merge_autodoc_default_flags ) from sphinx.ext.autodoc.directive import DocumenterBridge, process_documenter_options from sphinx.testing.util import SphinxTestApp, Struct # NOQA @@ -1456,35 +1456,26 @@ def test_partialmethod(app): @pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_autodoc_default_flags__as_list__converted(app): - orig = [ - 'members', - 'undoc-members', - ('skipped', 1, 2), - {'also': 'skipped'}, - ] - expected = { - 'members': None, - 'undoc-members': None, - } - app.config.autodoc_default_flags = orig - convert_autodoc_default_flags(app, app.config) - assert app.config.autodoc_default_flags == expected +def test_merge_autodoc_default_flags1(app): + app.config.autodoc_default_flags = ['members', 'undoc-members'] + merge_autodoc_default_flags(app, app.config) + assert app.config.autodoc_default_options == {'members': None, + 'undoc-members': None} @pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_autodoc_default_flags__as_dict__no_conversion(app): - orig = { - 'members': 'this,that,other', - 'undoc-members': None, - } - app.config.autodoc_default_flags = orig - convert_autodoc_default_flags(app, app.config) - assert app.config.autodoc_default_flags == orig +def test_merge_autodoc_default_flags2(app): + app.config.autodoc_default_flags = ['members', 'undoc-members'] + app.config.autodoc_default_options = {'members': 'this,that,order', + 'inherited-members': 'this'} + merge_autodoc_default_flags(app, app.config) + assert app.config.autodoc_default_options == {'members': None, + 'undoc-members': None, + 'inherited-members': 'this'} @pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_autodoc_default_flags__with_flags(app): +def test_autodoc_default_options(app): # no settings actual = do_autodoc(app, 'class', 'target.EnumCls') assert ' .. py:attribute:: EnumCls.val1' not in actual @@ -1493,13 +1484,13 @@ def test_autodoc_default_flags__with_flags(app): assert ' .. py:method:: target.CustomIter' not in actual # with :members: - app.config.autodoc_default_flags = {'members': None} + app.config.autodoc_default_options = {'members': None} actual = do_autodoc(app, 'class', 'target.EnumCls') assert ' .. py:attribute:: EnumCls.val1' in actual assert ' .. py:attribute:: EnumCls.val4' not in actual # with :members: and :undoc-members: - app.config.autodoc_default_flags = { + app.config.autodoc_default_options = { 'members': None, 'undoc-members': None, } @@ -1509,7 +1500,7 @@ def test_autodoc_default_flags__with_flags(app): # with :special-members: # Note that :members: must be *on* for :special-members: to work. - app.config.autodoc_default_flags = { + app.config.autodoc_default_options = { 'members': None, 'special-members': None } @@ -1525,14 +1516,14 @@ def test_autodoc_default_flags__with_flags(app): # :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 = { + app.config.autodoc_default_options = { '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 = { + app.config.autodoc_default_options = { 'members': None, 'special-members': None, 'exclude-members': None, @@ -1550,9 +1541,9 @@ def test_autodoc_default_flags__with_flags(app): @pytest.mark.sphinx('html', testroot='ext-autodoc') -def test_autodoc_default_flags__with_values(app): +def test_autodoc_default_options_with_values(app): # with :members: - app.config.autodoc_default_flags = {'members': 'val1,val2'} + app.config.autodoc_default_options = {'members': 'val1,val2'} actual = do_autodoc(app, 'class', 'target.EnumCls') assert ' .. py:attribute:: EnumCls.val1' in actual assert ' .. py:attribute:: EnumCls.val2' in actual @@ -1561,7 +1552,7 @@ def test_autodoc_default_flags__with_values(app): # with :special-members: # Note that :members: must be *on* for :special-members: to work. - app.config.autodoc_default_flags = { + app.config.autodoc_default_options = { 'members': None, 'special-members': '__init__,__iter__', } @@ -1575,7 +1566,7 @@ def test_autodoc_default_flags__with_values(app): assert ' list of weak references to the object (if defined)' not in actual # with :exclude-members: - app.config.autodoc_default_flags = { + app.config.autodoc_default_options = { 'members': None, 'exclude-members': 'val1' } @@ -1584,7 +1575,7 @@ def test_autodoc_default_flags__with_values(app): 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 = { + app.config.autodoc_default_options = { 'members': None, 'special-members': None, 'exclude-members': '__weakref__,snafucate',