Close #4030: autosummary: Add autosummary_context

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

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

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

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

tests/roots/test-templating/_templates/autosummary/class.rst

@@ -3,6 +3,7 @@
 {% block methods %}
 
    .. note:: autosummary/class.rst method block overloading
+             {{ sentence }}
 
    {{ super() }}
 {% endblock %}

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

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