Fix #8306: autosummary: mocked modules are documented as empty page

The :recursive: option for autosummary directive creates an empty page
for mocked modules unexpectedly.  This make them ignored.

CHANGES

@@ -18,6 +18,8 @@ Bugs fixed
 
 * #741: autodoc: inherited-members doesn't work for instance attributes on super
   class
+* #8306: autosummary: mocked modules are documented as empty page when using
+  :recursive: option
 
 Testing
 --------

sphinx/ext/autosummary/generate.py

@@ -40,6 +40,7 @@ from sphinx.builders import Builder
 from sphinx.config import Config
 from sphinx.deprecation import RemovedInSphinx40Warning, RemovedInSphinx50Warning
 from sphinx.ext.autodoc import Documenter
+from sphinx.ext.autodoc.importer import import_module
 from sphinx.ext.autosummary import get_documenter, import_by_name, import_ivar_by_name
 from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
@@ -285,6 +286,13 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         items = []  # type: List[str]
         for _, modname, ispkg in pkgutil.iter_modules(obj.__path__):
             fullname = name + '.' + modname
+            try:
+                module = import_module(fullname)
+                if module and hasattr(module, '__sphinx_mock__'):
+                    continue
+            except ImportError:
+                pass
+
             items.append(fullname)
         public = [x for x in items if not x.split('.')[-1].startswith('_')]
         return public, items

tests/test_ext_autosummary.py

@@ -379,27 +379,47 @@ def test_autosummary_generate_overwrite2(app_params, make_app):
 
 @pytest.mark.sphinx('dummy', testroot='ext-autosummary-recursive')
 def test_autosummary_recursive(app, status, warning):
-    app.build()
+    try:
+        app.build()
 
-    # autosummary having :recursive: option
+        # autosummary having :recursive: option
-    assert (app.srcdir / 'generated' / 'package.rst').exists()
+        assert (app.srcdir / 'generated' / 'package.rst').exists()
-    assert (app.srcdir / 'generated' / 'package.module.rst').exists()
+        assert (app.srcdir / 'generated' / 'package.module.rst').exists()
-    assert (app.srcdir / 'generated' / 'package.module_importfail.rst').exists() is False
+        assert (app.srcdir / 'generated' / 'package.module_importfail.rst').exists() is False
-    assert (app.srcdir / 'generated' / 'package.package.rst').exists()
+        assert (app.srcdir / 'generated' / 'package.package.rst').exists()
-    assert (app.srcdir / 'generated' / 'package.package.module.rst').exists()
+        assert (app.srcdir / 'generated' / 'package.package.module.rst').exists()
 
-    # autosummary not having :recursive: option
+        # autosummary not having :recursive: option
-    assert (app.srcdir / 'generated' / 'package2.rst').exists()
+        assert (app.srcdir / 'generated' / 'package2.rst').exists()
-    assert (app.srcdir / 'generated' / 'package2.module.rst').exists() is False
+        assert (app.srcdir / 'generated' / 'package2.module.rst').exists() is False
 
-    # Check content of recursively generated stub-files
+        # Check content of recursively generated stub-files
-    content = (app.srcdir / 'generated' / 'package.rst').read_text()
+        content = (app.srcdir / 'generated' / 'package.rst').read_text()
-    assert 'package.module' in content
+        assert 'package.module' in content
-    assert 'package.package' in content
+        assert 'package.package' in content
-    assert 'package.module_importfail' in content
+        assert 'package.module_importfail' in content
 
-    content = (app.srcdir / 'generated' / 'package.package.rst').read_text()
+        content = (app.srcdir / 'generated' / 'package.package.rst').read_text()
-    assert 'package.package.module' in content
+        assert 'package.package.module' in content
+    finally:
+        sys.modules.pop('package.package', None)
+        sys.modules.pop('package.package.module', None)
+
+
+@pytest.mark.sphinx('dummy', testroot='ext-autosummary-recursive',
+                    srcdir='test_autosummary_recursive_skips_mocked_modules',
+                    confoverrides={'autosummary_mock_imports': ['package.package']})
+def test_autosummary_recursive_skips_mocked_modules(app, status, warning):
+    try:
+        app.build()
+
+        assert (app.srcdir / 'generated' / 'package.rst').exists()
+        assert (app.srcdir / 'generated' / 'package.module.rst').exists()
+        assert (app.srcdir / 'generated' / 'package.package.rst').exists() is False
+        assert (app.srcdir / 'generated' / 'package.package.module.rst').exists() is False
+    finally:
+        sys.modules.pop('package.package', None)
+        sys.modules.pop('package.package.module', None)
 
 
 @pytest.mark.sphinx('dummy', testroot='ext-autosummary-filename-map')