Merge pull request #8601 from tk0miya/8306_autosummary_mocks_are_docu…

…mented

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

CHANGES

@@ -27,6 +27,8 @@ Bugs fixed
   class
 * #8592: autodoc: ``:meta public:`` does not effect to variables
 * #8594: autodoc: empty __all__ attribute is ignored
+* #8306: autosummary: mocked modules are documented as empty page when using
+  :recursive: option
 * #8094: texinfo: image files on the different directory with document are not
   copied
 

sphinx/ext/autosummary/generate.py

@@ -40,6 +40,7 @@
 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 get_modules(obj: Any) -> Tuple[List[str], List[str]]:
         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
+        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')