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.

3 files changed, 50 insertions, 20 deletions

diff --git a/CHANGES b/CHANGES
index 9360f3473..5ab2377c0 100644
--- a/CHANGES
+++ b/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
 --------
diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py
index 10f8ca913..949d8cdbe 100644
--- a/sphinx/ext/autosummary/generate.py
+++ b/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
diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py
index 6e0ca21c7..7cffca4f3 100644
--- a/tests/test_ext_autosummary.py
+++ b/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
+        assert (app.srcdir / 'generated' / 'package.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.package.rst').exists()
+        assert (app.srcdir / 'generated' / 'package.package.module.rst').exists()
+
+        # autosummary not having :recursive: option
+        assert (app.srcdir / 'generated' / 'package2.rst').exists()
+        assert (app.srcdir / 'generated' / 'package2.module.rst').exists() is False
+
+        # Check content of recursively generated stub-files
+        content = (app.srcdir / 'generated' / 'package.rst').read_text()
+        assert 'package.module' in content
+        assert 'package.package' in content
+        assert 'package.module_importfail' in content
+
+        content = (app.srcdir / 'generated' / 'package.package.rst').read_text()
+        assert 'package.package.module' in content
+    finally:
+        sys.modules.pop('package.package', None)
+        sys.modules.pop('package.package.module', None)
 
-    # autosummary having :recursive: option
-    assert (app.srcdir / 'generated' / 'package.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.package.rst').exists()
-    assert (app.srcdir / 'generated' / 'package.package.module.rst').exists()
-
-    # autosummary not having :recursive: option
-    assert (app.srcdir / 'generated' / 'package2.rst').exists()
-    assert (app.srcdir / 'generated' / 'package2.module.rst').exists() is False
-
-    # Check content of recursively generated stub-files
-    content = (app.srcdir / 'generated' / 'package.rst').read_text()
-    assert 'package.module' in content
-    assert 'package.package' in content
-    assert 'package.module_importfail' in content
-
-    content = (app.srcdir / 'generated' / 'package.package.rst').read_text()
-    assert 'package.package.module' in content
+
+@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')