autosummary: Respect empty module __all__ (#13187)

Co-authored-by: Adam Turner <[email protected]>

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

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(

tests/roots/test-ext-autosummary-module_empty_all/autosummary_dummy_package_empty_all/__init__.py

@@ -0,0 +1 @@
+__all__ = ()

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

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

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

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