#5877: Allow setting imported_members for autosummary in conf.py

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
 ---------------------
 

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}

tests/roots/test-ext-autosummary-imported_members/autosummary_dummy_package/__init__.py

@@ -0,0 +1 @@
+from .autosummary_dummy_module import Bar, foo

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

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

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

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

tests/test_ext_autosummary.py

@@ -242,3 +242,23 @@ 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()
+        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)