Fix #8870: Use title node for the caption of toctree

Since docutils-0.17, the caption node should not use for the non-figure
nodes.  Therefore, this replaces it by the title node.

6 files changed, 22 insertions, 13 deletions

diff --git a/CHANGES b/CHANGES
index f8bf859e1..6444c93fd 100644
--- a/CHANGES
+++ b/CHANGES
@@ -16,6 +16,8 @@ Features added
 Bugs fixed
 ----------
 
+* #8870: The style of toctree captions has been changed with docutils-0.17
+
 Testing
 --------
 
diff --git a/sphinx/environment/adapters/toctree.py b/sphinx/environment/adapters/toctree.py
index 93555d172..f0a37ab7f 100644
--- a/sphinx/environment/adapters/toctree.py
+++ b/sphinx/environment/adapters/toctree.py
@@ -237,7 +237,7 @@ class TocTree:
         newnode = addnodes.compact_paragraph('', '')
         caption = toctree.attributes.get('caption')
         if caption:
-            caption_node = nodes.caption(caption, '', *[nodes.Text(caption)])
+            caption_node = nodes.title(caption, '', *[nodes.Text(caption)])
             caption_node.line = toctree.line
             caption_node.source = toctree.source
             caption_node.rawsource = toctree['rawcaption']
diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py
index d3e7e03a4..b3364a68e 100644
--- a/sphinx/writers/html.py
+++ b/sphinx/writers/html.py
@@ -404,7 +404,12 @@ class HTMLTranslator(SphinxTranslator, BaseTranslator):
 
     # overwritten
     def visit_title(self, node: Element) -> None:
-        super().visit_title(node)
+        if isinstance(node.parent, addnodes.compact_paragraph) and node.parent.get('toctree'):
+            self.body.append(self.starttag(node, 'p', '', CLASS='caption'))
+            self.body.append('<span class="caption-text">')
+            self.context.append('</span></p>\n')
+        else:
+            super().visit_title(node)
         self.add_secnumber(node)
         self.add_fignumber(node.parent)
         if isinstance(node.parent, nodes.table):
diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py
index 5666e4d02..bdaffe140 100644
--- a/sphinx/writers/html5.py
+++ b/sphinx/writers/html5.py
@@ -355,7 +355,12 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
 
     # overwritten
     def visit_title(self, node: Element) -> None:
-        super().visit_title(node)
+        if isinstance(node.parent, addnodes.compact_paragraph) and node.parent.get('toctree'):
+            self.body.append(self.starttag(node, 'p', '', CLASS='caption'))
+            self.body.append('<span class="caption-text">')
+            self.context.append('</span></p>\n')
+        else:
+            super().visit_title(node)
         self.add_secnumber(node)
         self.add_fignumber(node.parent)
         if isinstance(node.parent, nodes.table):
diff --git a/tests/test_environment_toctree.py b/tests/test_environment_toctree.py
index 41b3f727c..85a98b61b 100644
--- a/tests/test_environment_toctree.py
+++ b/tests/test_environment_toctree.py
@@ -10,7 +10,7 @@
 
 import pytest
 from docutils import nodes
-from docutils.nodes import bullet_list, caption, comment, list_item, reference
+from docutils.nodes import bullet_list, comment, list_item, reference, title
 
 from sphinx import addnodes
 from sphinx.addnodes import compact_paragraph, only
@@ -211,7 +211,7 @@ def test_get_toctree_for(app):
     app.build()
     toctree = TocTree(app.env).get_toctree_for('index', app.builder, collapse=False)
     assert_node(toctree,
-                [compact_paragraph, ([caption, "Table of Contents"],
+                [compact_paragraph, ([title, "Table of Contents"],
                                      bullet_list,
                                      bullet_list,
                                      bullet_list)])
@@ -251,7 +251,7 @@ def test_get_toctree_for_collapse(app):
     app.build()
     toctree = TocTree(app.env).get_toctree_for('index', app.builder, collapse=True)
     assert_node(toctree,
-                [compact_paragraph, ([caption, "Table of Contents"],
+                [compact_paragraph, ([title, "Table of Contents"],
                                      bullet_list,
                                      bullet_list,
                                      bullet_list)])
@@ -283,7 +283,7 @@ def test_get_toctree_for_maxdepth(app):
     toctree = TocTree(app.env).get_toctree_for('index', app.builder,
                                                collapse=False, maxdepth=3)
     assert_node(toctree,
-                [compact_paragraph, ([caption, "Table of Contents"],
+                [compact_paragraph, ([title, "Table of Contents"],
                                      bullet_list,
                                      bullet_list,
                                      bullet_list)])
@@ -329,7 +329,7 @@ def test_get_toctree_for_includehidden(app):
     toctree = TocTree(app.env).get_toctree_for('index', app.builder, collapse=False,
                                                includehidden=False)
     assert_node(toctree,
-                [compact_paragraph, ([caption, "Table of Contents"],
+                [compact_paragraph, ([title, "Table of Contents"],
                                      bullet_list,
                                      bullet_list)])
 
diff --git a/tests/test_intl.py b/tests/test_intl.py
index 3a704fd7d..0e4387025 100644
--- a/tests/test_intl.py
+++ b/tests/test_intl.py
@@ -622,11 +622,8 @@ def test_html_meta(app):
     assert expected_expr in result
     expected_expr = '<meta content="I18N, SPHINX, MARKUP" name="keywords" />'
     assert expected_expr in result
-    if docutils.__version_info__ < (0, 17):
-        expected_expr = '<p class="caption"><span class="caption-text">HIDDEN TOC</span></p>'
-        assert expected_expr in result
-    else:
-        expected_expr = '<p><span class="caption-text">HIDDEN TOC</span></p>'
+    expected_expr = '<p class="caption"><span class="caption-text">HIDDEN TOC</span></p>'
+    assert expected_expr in result
 
 
 @sphinx_intl