diff --git a/CHANGES.rst b/CHANGES.rst index 8f856b1f6..69c4ada5c 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -54,6 +54,8 @@ Features added Bugs fixed ---------- +* #12463: autosummary: Respect an empty module ``__all__``. + Patch by Valentin Pratz * #13060: HTML Search: use ``Map`` to store per-file term scores. Patch by James Addison * #13130: LaTeX docs: ``pdflatex`` index creation may fail for index entries diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 48d50a191..617fc495b 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -275,7 +275,11 @@ def members_of(obj: Any, conf: Config) -> Sequence[str]: if conf.autosummary_ignore_module_all: return dir(obj) else: - return getall(obj) or dir(obj) + if (obj___all__ := getall(obj)) is not None: + # return __all__, even if empty. + return obj___all__ + # if __all__ is not set, return dir(obj) + return dir(obj) def generate_autosummary_content( diff --git a/tests/roots/test-ext-autosummary-module_empty_all/autosummary_dummy_package_empty_all/__init__.py b/tests/roots/test-ext-autosummary-module_empty_all/autosummary_dummy_package_empty_all/__init__.py new file mode 100644 index 000000000..ea9b78354 --- /dev/null +++ b/tests/roots/test-ext-autosummary-module_empty_all/autosummary_dummy_package_empty_all/__init__.py @@ -0,0 +1 @@ +__all__ = () diff --git a/tests/roots/test-ext-autosummary-module_empty_all/conf.py b/tests/roots/test-ext-autosummary-module_empty_all/conf.py new file mode 100644 index 000000000..9062c5ceb --- /dev/null +++ b/tests/roots/test-ext-autosummary-module_empty_all/conf.py @@ -0,0 +1,11 @@ +import sys +from pathlib import Path + +sys.path.insert(0, str(Path.cwd().resolve())) + +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary'] +autodoc_default_options = {'members': True} +autosummary_ignore_module_all = False +autosummary_imorted_members = False + +templates_path = ['templates'] diff --git a/tests/roots/test-ext-autosummary-module_empty_all/index.rst b/tests/roots/test-ext-autosummary-module_empty_all/index.rst new file mode 100644 index 000000000..41afaf378 --- /dev/null +++ b/tests/roots/test-ext-autosummary-module_empty_all/index.rst @@ -0,0 +1,8 @@ +test-ext-autosummary-module_all +=============================== + +.. autosummary:: + :toctree: generated + :recursive: + + autosummary_dummy_package_empty_all diff --git a/tests/roots/test-ext-autosummary-module_empty_all/templates/autosummary/module.rst b/tests/roots/test-ext-autosummary-module_empty_all/templates/autosummary/module.rst new file mode 100644 index 000000000..c7803af69 --- /dev/null +++ b/tests/roots/test-ext-autosummary-module_empty_all/templates/autosummary/module.rst @@ -0,0 +1,13 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block members %} + Summary + ------- + .. autosummary:: + + {% for item in members %} + {{ item }} + {%- endfor %} + {% endblock %} diff --git a/tests/test_extensions/test_ext_autosummary.py b/tests/test_extensions/test_ext_autosummary.py index 901edb299..c80753bef 100644 --- a/tests/test_extensions/test_ext_autosummary.py +++ b/tests/test_extensions/test_ext_autosummary.py @@ -826,9 +826,8 @@ def test_autosummary_module_all(app): app.build() # generated/foo is generated successfully assert app.env.get_doctree('generated/autosummary_dummy_package_all') - module = ( - app.srcdir / 'generated' / 'autosummary_dummy_package_all.rst' - ).read_text(encoding='utf8') + path = app.srcdir / 'generated' / 'autosummary_dummy_package_all.rst' + module = path.read_text(encoding='utf8') assert ' .. autosummary::\n \n PublicBar\n \n' in module assert ( ' .. autosummary::\n \n public_foo\n public_baz\n \n' @@ -840,6 +839,30 @@ def test_autosummary_module_all(app): sys.modules.pop('autosummary_dummy_package_all', None) +@pytest.mark.sphinx('dummy', testroot='ext-autosummary-module_empty_all') +def test_autosummary_module_empty_all(app): + try: + app.build() + # generated/foo is generated successfully + assert app.env.get_doctree('generated/autosummary_dummy_package_empty_all') + path = app.srcdir / 'generated' / 'autosummary_dummy_package_empty_all.rst' + module = path.read_text(encoding='utf8') + assert '.. automodule:: autosummary_dummy_package_empty_all' in module + # for __all__ = (), the output should not contain any variables + assert '__all__' not in module + assert '__builtins__' not in module + assert '__cached__' not in module + assert '__doc__' not in module + assert '__file__' not in module + assert '__loader__' not in module + assert '__name__' not in module + assert '__package__' not in module + assert '__path__' not in module + assert '__spec__' not in module + finally: + sys.modules.pop('autosummary_dummy_package_all', None) + + @pytest.mark.sphinx( 'html', testroot='ext-autodoc',