Merge pull request #5315 from tk0miya/add_autodoc_default_options

Add autodoc_default_options

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
 ----------

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

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
 

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}

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))
 

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',