From c1c7cf8c8ceb2295d40b28abebd4df585adac26d Mon Sep 17 00:00:00 2001 From: tsanikgr Date: Wed, 27 Mar 2019 13:40:45 +0000 Subject: [PATCH] #5877: Allow setting imported_members for autosummary in conf.py --- doc/usage/extensions/autosummary.rst | 11 ++++++++++ sphinx/ext/autosummary/__init__.py | 4 +++- .../autosummary_dummy_package/__init__.py | 1 + .../autosummary_dummy_module.py | 8 +++++++ .../conf.py | 7 +++++++ .../index.rst | 7 +++++++ tests/test_ext_autosummary.py | 21 +++++++++++++++++++ 7 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 tests/roots/test-ext-autosummary-imported_members/autosummary_dummy_package/__init__.py create mode 100644 tests/roots/test-ext-autosummary-imported_members/autosummary_dummy_package/autosummary_dummy_module.py create mode 100644 tests/roots/test-ext-autosummary-imported_members/conf.py create mode 100644 tests/roots/test-ext-autosummary-imported_members/index.rst diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index d1ac0ad32..4afd19544 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -99,6 +99,12 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: .. versionadded:: 1.0 + * You can specify to documented imported classes and functions at a module + level using the new :confval:`autosummary_imported_members` config value. + By default this if disabled. + + .. versionadded:: 2.1.1 + :program:`sphinx-autogen` -- generate autodoc stub pages -------------------------------------------------------- @@ -149,6 +155,11 @@ also use these config values: :confval:`autodoc_mock_imports` for more details. It defaults to :confval:`autodoc_mock_imports`. +.. confval:: autosummary_imported_members + + A boolean flag indicating whether to document classes and functions imported + in modules. Default is ``False`` + Customizing templates --------------------- diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 4cd1638d6..03771e956 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -703,11 +703,12 @@ def process_generate_options(app): 'But your source_suffix does not contain .rst. Skipped.')) return + imported_members = app.config.autosummary_imported_members 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) + app=app, imported_members=imported_members) def setup(app): @@ -733,5 +734,6 @@ def setup(app): app.add_config_value('autosummary_generate', [], True, [bool]) app.add_config_value('autosummary_mock_imports', lambda config: config.autodoc_mock_imports, 'env') + app.add_config_value('autosummary_imported_members', [], False, [bool]) return {'version': sphinx.__display_version__, 'parallel_read_safe': True} diff --git a/tests/roots/test-ext-autosummary-imported_members/autosummary_dummy_package/__init__.py b/tests/roots/test-ext-autosummary-imported_members/autosummary_dummy_package/__init__.py new file mode 100644 index 000000000..0a7d9f382 --- /dev/null +++ b/tests/roots/test-ext-autosummary-imported_members/autosummary_dummy_package/__init__.py @@ -0,0 +1 @@ +from .autosummary_dummy_module import Bar, foo diff --git a/tests/roots/test-ext-autosummary-imported_members/autosummary_dummy_package/autosummary_dummy_module.py b/tests/roots/test-ext-autosummary-imported_members/autosummary_dummy_package/autosummary_dummy_module.py new file mode 100644 index 000000000..9c93f064e --- /dev/null +++ b/tests/roots/test-ext-autosummary-imported_members/autosummary_dummy_package/autosummary_dummy_module.py @@ -0,0 +1,8 @@ +class Bar: + """Bar class""" + pass + + +def foo(): + """Foo function""" + pass diff --git a/tests/roots/test-ext-autosummary-imported_members/conf.py b/tests/roots/test-ext-autosummary-imported_members/conf.py new file mode 100644 index 000000000..4cfff02dc --- /dev/null +++ b/tests/roots/test-ext-autosummary-imported_members/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_imported_members = True diff --git a/tests/roots/test-ext-autosummary-imported_members/index.rst b/tests/roots/test-ext-autosummary-imported_members/index.rst new file mode 100644 index 000000000..608ca2954 --- /dev/null +++ b/tests/roots/test-ext-autosummary-imported_members/index.rst @@ -0,0 +1,7 @@ +test-ext-autosummary-mock_imports +================================= + +.. autosummary:: + :toctree: generated + + autosummary_dummy_package diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index 3cc9710d8..4f7b69ebb 100644 --- a/tests/test_ext_autosummary.py +++ b/tests/test_ext_autosummary.py @@ -242,3 +242,24 @@ def test_autosummary_mock_imports(app, status, warning): assert app.env.get_doctree('generated/foo') finally: sys.modules.pop('foo', None) # unload foo module + + +@pytest.mark.sphinx('dummy', testroot='ext-autosummary-imported_members') +def test_autosummary_imported_members(app, status, warning): + try: + app.build() + # generated/foo is generated successfully + assert app.env.get_doctree('generated/autosummary_dummy_package') + + module = (app.srcdir / 'generated' / 'autosummary_dummy_package.rst').text() + print(module) + assert (' .. autosummary::\n' + ' \n' + ' Bar\n' + ' \n' in module) + assert (' .. autosummary::\n' + ' \n' + ' foo\n' + ' \n' in module) + finally: + sys.modules.pop('autosummary_dummy_package', None)