diff --git a/CHANGES b/CHANGES index bebfc5500..cd6c247aa 100644 --- a/CHANGES +++ b/CHANGES @@ -41,6 +41,8 @@ Features added caption to the toctree * #248, #6040: autosummary: Add ``:recursive:`` option to autosummary directive to generate stub files recursively +* #4030: autosummary: Add :confval:`autosummary_context` to add template + variables for custom templates * #7535: sphinx-autogen: crashes when custom template uses inheritance * #7536: sphinx-autogen: crashes when template uses i18n feature * #7481: html theme: Add right margin to footnote/citation labels diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 5915b30cd..f3a5aea0e 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -151,6 +151,13 @@ Generating stub pages automatically If you do not want to create stub pages with :program:`sphinx-autogen`, you can also use these config values: +.. confval:: autosummary_context + + A dictionary of values to pass into the template engine's context for + autosummary stubs files. + + .. versionadded:: 3.1 + .. confval:: autosummary_generate Boolean indicating whether to scan all found documents for autosummary diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 23527d5c8..7d1a7a598 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -776,6 +776,7 @@ def setup(app: Sphinx) -> Dict[str, Any]: app.add_directive('autosummary', Autosummary) app.add_role('autolink', AutoLink()) app.connect('builder-inited', process_generate_options) + app.add_config_value('autosummary_context', {}, True) app.add_config_value('autosummary_generate', [], True, [bool]) app.add_config_value('autosummary_generate_overwrite', True, False) app.add_config_value('autosummary_mock_imports', diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index df7ad4b1d..69aac2df5 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -70,6 +70,7 @@ class DummyApplication: self._warncount = 0 self.warningiserror = False + self.config.add('autosummary_context', {}, True, None) self.config.init_values() def emit_firstresult(self, *args: Any) -> None: @@ -164,7 +165,7 @@ class AutosummaryRenderer: def generate_autosummary_content(name: str, obj: Any, parent: Any, template: AutosummaryRenderer, template_name: str, imported_members: bool, app: Any, - recursive: bool) -> str: + recursive: bool, context: Dict) -> str: doc = get_documenter(app, obj, parent) if template_name is None: @@ -218,6 +219,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any, return public, items ns = {} # type: Dict[str, Any] + ns.update(context) if doc.objtype == 'module': ns['members'] = dir(obj) @@ -323,8 +325,12 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, _warn(__('[autosummary] failed to import %r: %s') % (entry.name, e)) continue + context = {} + if app: + context.update(app.config.autosummary_context) + content = generate_autosummary_content(name, obj, parent, template, entry.template, - imported_members, app, entry.recursive) + imported_members, app, entry.recursive, context) filename = os.path.join(path, name + suffix) if os.path.isfile(filename): diff --git a/tests/roots/test-templating/_templates/autosummary/class.rst b/tests/roots/test-templating/_templates/autosummary/class.rst index 7f1536173..6f505649c 100644 --- a/tests/roots/test-templating/_templates/autosummary/class.rst +++ b/tests/roots/test-templating/_templates/autosummary/class.rst @@ -3,6 +3,7 @@ {% block methods %} .. note:: autosummary/class.rst method block overloading + {{ sentence }} {{ super() }} {% endblock %} diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index 7e7a20663..114694166 100644 --- a/tests/test_ext_autosummary.py +++ b/tests/test_ext_autosummary.py @@ -353,7 +353,8 @@ def test_autosummary_imported_members(app, status, warning): sys.modules.pop('autosummary_dummy_package', None) -@pytest.mark.sphinx(testroot='ext-autodoc') +@pytest.mark.sphinx(testroot='ext-autodoc', + confoverrides={'extensions': ['sphinx.ext.autosummary']}) def test_generate_autosummary_docs_property(app): with patch('sphinx.ext.autosummary.generate.find_autosummary_in_files') as mock: mock.return_value = [AutosummaryEntry('target.methods.Base.prop', 'prop', None, False)] diff --git a/tests/test_templating.py b/tests/test_templating.py index becacda0d..f2c1d563b 100644 --- a/tests/test_templating.py +++ b/tests/test_templating.py @@ -33,3 +33,17 @@ def test_autosummary_class_template_overloading(make_app, app_params): result = (app.outdir / 'generated' / 'sphinx.application.TemplateBridge.html').read_text() assert 'autosummary/class.rst method block overloading' in result + assert 'foobar' not in result + + +@pytest.mark.sphinx('html', testroot='templating', + confoverrides={'autosummary_context': {'sentence': 'foobar'}}) +def test_autosummary_context(make_app, app_params): + args, kwargs = app_params + app = make_app(*args, **kwargs) + setup_documenters(app) + app.builder.build_update() + + result = (app.outdir / 'generated' / 'sphinx.application.TemplateBridge.html').read_text() + assert 'autosummary/class.rst method block overloading' in result + assert 'foobar' in result