Merge pull request #6064 from tk0miya/5636_add_autosummary_mock_imports

Closes #5635: autosummary: Add autosummary_mock_imports to mock external libraries

CHANGES

@@ -166,6 +166,8 @@ Features added
 * #5533: autodoc: :confval:`autodoc_default_options` supports ``member-order``
 * #5394: autodoc: Display readable names in type annotations for mocked objects
 * #5459: autodoc: :confval:`autodoc_default_options` accepts ``True`` as a value
+* #5635: autosummary: Add :confval:`autosummary_mock_imports` to mock external
+  libraries on importing targets
 * #4018: htmlhelp: Add :confval:`htmlhelp_file_suffix` and
   :confval:`htmlhelp_link_suffix`
 * #5559: text: Support complex tables (colspan and rowspan)

doc/usage/extensions/autosummary.rst

@@ -143,6 +143,11 @@ also use this new config value:
    The new files will be placed in the directories specified in the
    ``:toctree:`` options of the directives.
 
+.. confval:: autosummary_mock_imports
+
+   This value contains a list of modules to be mocked up.  See
+   :confval:`autodoc_mock_imports` for more details.  It defaults to
+   :confval:`autodoc_mock_imports`.
 
 Customizing templates
 ---------------------

sphinx/ext/autosummary/__init__.py

@@ -72,7 +72,7 @@ from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.ext.autodoc import get_documenters
 from sphinx.ext.autodoc.directive import DocumenterBridge, Options
-from sphinx.ext.autodoc.importer import import_module
+from sphinx.ext.autodoc.importer import import_module, mock
 from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.util import import_object, rst, logging
@@ -286,7 +286,8 @@ class Autosummary(SphinxDirective):
                 display_name = name.split('.')[-1]
 
             try:
-                real_name, obj, parent, modname = import_by_name(name, prefixes=prefixes)
+                with mock(self.config.autosummary_mock_imports):
+                    real_name, obj, parent, modname = import_by_name(name, prefixes=prefixes)
             except ImportError:
                 logger.warning(__('failed to import %s'), name)
                 items.append((name, '', '', name))
@@ -702,10 +703,11 @@ def process_generate_options(app):
                           'But your source_suffix does not contain .rst. Skipped.'))
         return
 
-    generate_autosummary_docs(genfiles, builder=app.builder,
-                              warn=logger.warning, info=logger.info,
-                              suffix=suffix, base_path=app.srcdir,
-                              app=app)
+    with mock(app.config.autosummary_mock_imports):
+        generate_autosummary_docs(genfiles, builder=app.builder,
+                                  warn=logger.warning, info=logger.info,
+                                  suffix=suffix, base_path=app.srcdir,
+                                  app=app)
 
 
 def setup(app):
@@ -729,4 +731,7 @@ def setup(app):
     app.connect('doctree-read', process_autosummary_toc)
     app.connect('builder-inited', process_generate_options)
     app.add_config_value('autosummary_generate', [], True, [bool])
+    app.add_config_value('autosummary_mock_imports',
+                         lambda config: config.autodoc_mock_imports, 'env')
+
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

tests/roots/test-ext-autosummary-mock_imports/conf.py

@@ -0,0 +1,7 @@
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions = ['sphinx.ext.autosummary']
+autosummary_generate = True
+autosummary_mock_imports = ['unknown']

tests/roots/test-ext-autosummary-mock_imports/foo.py

@@ -0,0 +1,6 @@
+import unknown
+
+
+class Foo(unknown.Class):
+    """Foo class"""
+    pass

tests/roots/test-ext-autosummary-mock_imports/index.rst

@@ -0,0 +1,7 @@
+test-ext-autosummary-mock_imports
+=================================
+
+.. autosummary::
+   :toctree: generated
+
+   foo

tests/test_ext_autosummary.py

@@ -8,6 +8,7 @@
     :license: BSD, see LICENSE for details.
 """
 
+import sys
 from io import StringIO
 
 import pytest
@@ -229,3 +230,15 @@ def test_import_by_name():
     assert obj == sphinx.ext.autosummary.Autosummary.get_items
     assert parent is sphinx.ext.autosummary.Autosummary
     assert modname == 'sphinx.ext.autosummary'
+
+
+@pytest.mark.sphinx('dummy', testroot='ext-autosummary-mock_imports')
+def test_autosummary_mock_imports(app, status, warning):
+    try:
+        app.build()
+        assert warning.getvalue() == ''
+
+        # generated/foo is generated successfully
+        assert app.env.get_doctree('generated/foo')
+    finally:
+        sys.modules.pop('foo', None)  # unload foo module