Add option to autosummary to generate pages for classes, etc

Closes sphinx-doc#7912

CHANGES

@@ -31,6 +31,9 @@ Features added
   Patch by Thomas Louf, Adam Turner, and Jean-François B.
 * #10983: Support for multiline copyright statements in the footer block.
   Patch by Stefanie Molin
+* Add :confval:`autosummary_recurse_members` option to make
+  :rst:dir:`autosummary` generate separate pages for classes and functions in
+  modules and packages.
 
 Bugs fixed
 ----------

sphinx/ext/autosummary/__init__.py

@@ -837,5 +837,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

@@ -71,6 +71,7 @@ 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.init_values()
 
     def emit_firstresult(self, *args: Any) -> None:
@@ -406,6 +407,8 @@ def get_modules(
     ns['objtype'] = doc.objtype
     ns['underline'] = len(name) * '='
 
+    ns['recurse_members'] = app.config.autosummary_recurse_members
+
     if template_name:
         return template.render(template_name, ns)
     else:

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

@@ -3,6 +3,11 @@
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
+   {% if recurse_members -%}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   {%- 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()