diff --git a/CHANGES b/CHANGES index 3a2f997ff47..8e20779c58d 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 3de8fb10722..99ddecadd0e 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/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 diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 035b94752ba..1634a898074 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/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} diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 1fceba4f362..494de6bc5e7 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/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: diff --git a/sphinx/ext/autosummary/templates/autosummary/class.rst b/sphinx/ext/autosummary/templates/autosummary/class.rst index 0f7d6f32e75..96cca9161cf 100644 --- a/sphinx/ext/autosummary/templates/autosummary/class.rst +++ b/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__ diff --git a/sphinx/ext/autosummary/templates/autosummary/module.rst b/sphinx/ext/autosummary/templates/autosummary/module.rst index e74c012f433..5c1693f1ec0 100644 --- a/sphinx/ext/autosummary/templates/autosummary/module.rst +++ b/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 %} diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index 1b56ef38eb2..1ed86cb4465 100644 --- a/tests/test_ext_autosummary.py +++ b/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()