Allow autosummary to create pages for classes, functions, etc

CHANGES

@@ -81,6 +81,9 @@ Features added
   configuration variable (:confval:`translation_progress_classes`).
   These enable determining the percentage of translated elements within
   a document, and the remaining translated and untranslated elements.
+* #11488: Add :confval:`autosummary_recurse_members` option to make
+  :rst:dir:`autosummary` generate separate pages for classes and functions in
+  modules and packages.
 
 Bugs fixed
 ----------

doc/usage/extensions/autosummary.rst

@@ -229,6 +229,13 @@ also use these config values:
 
    .. versionadded:: 3.2
 
+.. confval:: autosummary_recurse_members
+
+   When recursing into packages and modules, also generate separate
+   pages for module classes, functions, and members.
+
+   .. versionadded:: 7.2
+
 .. _autosummary-customizing-templates:
 
 Customizing templates

sphinx/ext/autosummary/__init__.py

@@ -840,5 +840,6 @@ def setup(app: Sphinx) -> dict[str, Any]:
                          lambda config: config.autodoc_mock_imports, 'env')
     app.add_config_value('autosummary_imported_members', [], False, [bool])
     app.add_config_value('autosummary_ignore_module_all', True, 'env', bool)
+    app.add_config_value('autosummary_recurse_members', False, True)
 
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

sphinx/ext/autosummary/generate.py

@@ -72,6 +72,8 @@ def __init__(self, translator: NullTranslations) -> None:
         self.config.add('autosummary_context', {}, True, None)
         self.config.add('autosummary_filename_map', {}, True, None)
         self.config.add('autosummary_ignore_module_all', True, 'env', bool)
+        self.config.add('autosummary_recurse_members', True, True, bool)
+        self.config.add('autodoc_inherit_docstrings', True, True, bool)
         self.config.init_values()
 
     def emit_firstresult(self, *args: Any) -> None:
@@ -407,6 +409,9 @@ def get_modules(
     ns['objtype'] = doc.objtype
     ns['underline'] = len(name) * '='
 
+    ns['recurse_members'] = app.config.autosummary_recurse_members
+    ns['inherit_docstrings'] = app.config.autodoc_inherit_docstrings
+
     if template_name:
         return template.render(template_name, ns)
     else:

sphinx/ext/autosummary/templates/autosummary/class.rst

@@ -3,6 +3,14 @@
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
+   {% if recurse_members -%}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   {% if inherit_docstrings -%}
+   :inherited-members:
+   {%- endif -%}
+   {%- endif %}
 
    {% block methods %}
    .. automethod:: __init__

sphinx/ext/autosummary/templates/autosummary/module.rst

@@ -7,6 +7,9 @@
    .. rubric:: {{ _('Module Attributes') }}
 
    .. autosummary::
+   {%- if recurse_members %}
+      :toctree:
+   {% endif %}
    {% for item in attributes %}
       {{ item }}
    {%- endfor %}
@@ -18,6 +21,9 @@
    .. rubric:: {{ _('Functions') }}
 
    .. autosummary::
+   {%- if recurse_members %}
+      :toctree:
+   {% endif %}
    {% for item in functions %}
       {{ item }}
    {%- endfor %}
@@ -29,6 +35,9 @@
    .. rubric:: {{ _('Classes') }}
 
    .. autosummary::
+   {%- if recurse_members %}
+      :toctree:
+   {% endif %}
    {% for item in classes %}
       {{ item }}
    {%- endfor %}
@@ -40,6 +49,9 @@
    .. rubric:: {{ _('Exceptions') }}
 
    .. autosummary::
+   {%- if recurse_members %}
+      :toctree:
+   {% endif %}
    {% for item in exceptions %}
       {{ item }}
    {%- endfor %}

tests/test_ext_autosummary.py

@@ -674,3 +674,11 @@ def test_autogen(rootdir, tempdir):
         args = ['-o', tempdir, '-t', '.', 'autosummary_templating.txt']
         autogen_main(args)
         assert (tempdir / 'sphinx.application.TemplateBridge.rst').exists()
+
+
+@pytest.mark.sphinx('dummy', testroot='ext-autosummary-recursive',
+                    srcdir='test_autosummary_recurse_members',
+                    confoverrides={'autosummary_recurse_members': True})
+def test_autosummary_recurse_members(app, status, warning):
+    app.build()
+    assert (app.srcdir / 'generated' / 'package.module.Foo.rst').exists()