From 73b8d6ff3342451e44de94ffca6b3c885ca6b425 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Mon, 11 Feb 2019 19:22:57 +0900 Subject: [PATCH] Closes #5636: autosummary: Add autosummary_mock_imports to mock external libraries --- CHANGES | 2 ++ doc/usage/extensions/autosummary.rst | 5 +++++ sphinx/ext/autosummary/__init__.py | 17 +++++++++++------ .../test-ext-autosummary-mock_imports/conf.py | 7 +++++++ .../test-ext-autosummary-mock_imports/foo.py | 6 ++++++ .../test-ext-autosummary-mock_imports/index.rst | 7 +++++++ tests/test_ext_autosummary.py | 13 +++++++++++++ 7 files changed, 51 insertions(+), 6 deletions(-) create mode 100644 tests/roots/test-ext-autosummary-mock_imports/conf.py create mode 100644 tests/roots/test-ext-autosummary-mock_imports/foo.py create mode 100644 tests/roots/test-ext-autosummary-mock_imports/index.rst diff --git a/CHANGES b/CHANGES index 4c032f04c..f16a62881 100644 --- a/CHANGES +++ b/CHANGES @@ -160,6 +160,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) diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 24e0d1855..eeb522950 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/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 --------------------- diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index a18ce2a6d..4cd1638d6 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/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} diff --git a/tests/roots/test-ext-autosummary-mock_imports/conf.py b/tests/roots/test-ext-autosummary-mock_imports/conf.py new file mode 100644 index 000000000..1097e3c04 --- /dev/null +++ b/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'] diff --git a/tests/roots/test-ext-autosummary-mock_imports/foo.py b/tests/roots/test-ext-autosummary-mock_imports/foo.py new file mode 100644 index 000000000..ab4460ef0 --- /dev/null +++ b/tests/roots/test-ext-autosummary-mock_imports/foo.py @@ -0,0 +1,6 @@ +import unknown + + +class Foo(unknown.Class): + """Foo class""" + pass diff --git a/tests/roots/test-ext-autosummary-mock_imports/index.rst b/tests/roots/test-ext-autosummary-mock_imports/index.rst new file mode 100644 index 000000000..f6044ed29 --- /dev/null +++ b/tests/roots/test-ext-autosummary-mock_imports/index.rst @@ -0,0 +1,7 @@ +test-ext-autosummary-mock_imports +================================= + +.. autosummary:: + :toctree: generated + + foo diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index 64c7df01c..63026beb5 100644 --- a/tests/test_ext_autosummary.py +++ b/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