Merge pull request #7492 from tk0miya/7490_autosummary_caption

Close #7490: autosummary: Add ``:caption:`` option to autosummary directive

CHANGES

@@ -25,6 +25,8 @@ Features added
 * C, added scope control directives, :rst:dir:`c:namespace`,
   :rst:dir:`c:namespace-push`, and :rst:dir:`c:namespace-pop`.
 * #7466: autosummary: headings in generated documents are not translated
+* #7490: autosummary: Add ``:caption:`` option to autosummary directive to set a
+  caption to the toctree
 * #7481: html theme: Add right margin to footnote/citation labels
 * #7482: html theme: CSS spacing for code blocks with captions and line numbers
 * #7443: html theme: Add new options :confval:`globaltoc_collapse` and

doc/usage/extensions/autosummary.rst

@@ -76,6 +76,12 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
      directory. If no argument is given, output is placed in the same directory
      as the file that contains the directive.
 
+     You can also use ``caption`` option to give a caption to the toctree.
+
+     .. versionadded:: 3.1
+
+        caption option added.
+
    * If you don't want the :rst:dir:`autosummary` to show function signatures in
      the listing, include the ``nosignatures`` option::
 

sphinx/ext/autosummary/__init__.py

@@ -228,6 +228,7 @@ class Autosummary(SphinxDirective):
     final_argument_whitespace = False
     has_content = True
     option_spec = {
+        'caption': directives.unchanged_required,
         'toctree': directives.unchanged,
         'nosignatures': directives.flag,
         'template': directives.unchanged,
@@ -270,9 +271,14 @@ class Autosummary(SphinxDirective):
                 tocnode['entries'] = [(None, docn) for docn in docnames]
                 tocnode['maxdepth'] = -1
                 tocnode['glob'] = None
+                tocnode['caption'] = self.options.get('caption')
 
                 nodes.append(autosummary_toc('', '', tocnode))
 
+        if 'toctree' not in self.options and 'caption' in self.options:
+            logger.warning(__('A captioned autosummary requires :toctree: option. ignored.'),
+                           location=nodes[-1])
+
         return nodes
 
     def get_items(self, names: List[str]) -> List[Tuple[str, str, str, str]]:

tests/roots/test-ext-autosummary/index.rst

@@ -5,6 +5,7 @@
 
 .. autosummary::
    :toctree: generated
+   :caption: An autosummary
 
    autosummary_dummy_module
    autosummary_dummy_module.Foo

tests/test_ext_autosummary.py

@@ -197,7 +197,7 @@ def test_autosummary_generate(app, status, warning):
                           nodes.paragraph,
                           addnodes.tabular_col_spec,
                           autosummary_table,
-                          autosummary_toc))
+                          [autosummary_toc, addnodes.toctree]))
     assert_node(doctree[3],
                 [autosummary_table, nodes.table, nodes.tgroup, (nodes.colspec,
                                                                 nodes.colspec,
@@ -205,6 +205,8 @@ def test_autosummary_generate(app, status, warning):
                                                                                nodes.row,
                                                                                nodes.row,
                                                                                nodes.row)])])
+    assert_node(doctree[4][0], addnodes.toctree, caption="An autosummary")
+
     assert doctree[3][0][0][2][0].astext() == 'autosummary_dummy_module\n\n'
     assert doctree[3][0][0][2][1].astext() == 'autosummary_dummy_module.Foo()\n\n'
     assert doctree[3][0][0][2][2].astext() == 'autosummary_dummy_module.bar(x[, y])\n\n'