diff --git a/CHANGES b/CHANGES index 8faa9ce97..9af836212 100644 --- a/CHANGES +++ b/CHANGES @@ -15,7 +15,10 @@ Features added * #9815: html theme: Wrap sidebar components in div to allow customizing their layout via CSS -* #9831: Autosummary now documents only the members specified in a module's ``__all__`` attribute if :confval:`autosummary_ignore___all__` is set to ``False``. The default behaviour is unchanged. +* #9831: Autosummary now documents only the members specified in a module's + ``__all__`` attribute if :confval:`autosummary_ignore___all__` is set to + ``False``. The default behaviour is unchanged. Autogen also now supports + this behavior with the ``--respect-module-all`` switch. Bugs fixed ---------- diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst index 18ae8d1e9..4c8f0f207 100644 --- a/doc/man/sphinx-autogen.rst +++ b/doc/man/sphinx-autogen.rst @@ -39,6 +39,10 @@ Options Document imported members. +.. option:: -a, --respect-module-all + + Document exactly the members in a module's ``__all__`` attribute. + Example ------- diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 6ce292a98..ac7bbd68f 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -201,12 +201,12 @@ also use these config values: .. versionadded:: 2.1 - .. versionchanged:: 4.3 + .. versionchanged:: 4.4 - If ``autosummary_ignore___all__`` is ``False``, this configuration value - is ignored for members listed in ``__all__``. + If ``autosummary_ignore_module_all`` is ``False``, this configuration + value is ignored for members listed in ``__all__``. -.. confval:: autosummary_ignore___all__ +.. confval:: autosummary_ignore_module_all If ``False`` and a module has the ``__all__`` attribute set, autosummary documents every member listed in ``__all__`` and no others. Default is @@ -215,10 +215,10 @@ also use these config values: Note that if an imported member is listed in ``__all__``, it will be documented regardless of the value of ``autosummary_imported_members``. To match the behaviour of ``from module import *``, set - ``autosummary_ignore___all__`` to False and ``autosummary_imported_members`` - to True. + ``autosummary_ignore_module_all`` to False and + ``autosummary_imported_members`` to True. - .. versionadded:: 4.3 + .. versionadded:: 4.4 .. confval:: autosummary_filename_map diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 6bca102e9..05363f3c7 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -645,7 +645,7 @@ The format of the autosummary directive is documented in the dest='imported_members', default=False, help=__('document imported members (default: ' '%(default)s)')) - parser.add_argument('-a', '--respect-__all__', action='store_false', + parser.add_argument('-a', '--respect-module-all', action='store_false', dest='ignore___all__', default=True, help=__('document exactly the members in module __all__ attribute. ' '(default: %(default)s)')) diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index 6f8cf853b..dd9b8c519 100644 --- a/tests/test_ext_autosummary.py +++ b/tests/test_ext_autosummary.py @@ -340,7 +340,7 @@ def test_autosummary_generate(app, status, warning): assert doctree[3][0][0][2][5].astext() == 'autosummary_dummy_module.qux\n\na module-level attribute' module = (app.srcdir / 'generated' / 'autosummary_dummy_module.rst').read_text() - print(module) + assert (' .. autosummary::\n' ' \n' ' Foo\n'