Make toctree accept 'genindex', 'modindex' and 'search' docnames

Fixes #8438

sphinx/directives/other.py

@@ -77,10 +77,11 @@ def run(self) -> List[Node]:
         return ret
 
     def parse_content(self, toctree: addnodes.toctree) -> List[Node]:
+        generated_documents = set(('genindex', 'modindex', 'search'))
         suffixes = self.config.source_suffix
 
         # glob target documents
-        all_docnames = self.env.found_docs.copy()
+        all_docnames = self.env.found_docs.copy() | generated_documents
         all_docnames.remove(self.env.docname)  # remove current document
 
         ret: List[Node] = []
@@ -118,7 +119,7 @@ def parse_content(self, toctree: addnodes.toctree) -> List[Node]:
                 docname = docname_join(self.env.docname, docname)
                 if url_re.match(ref) or ref == 'self':
                     toctree['entries'].append((title, ref))
-                elif docname not in self.env.found_docs:
+                elif docname not in (self.env.found_docs | generated_documents):
                     if excluded(self.env.doc2path(docname, None)):
                         message = __('toctree contains reference to excluded document %r')
                         subtype = 'excluded'

sphinx/environment/adapters/toctree.py

@@ -138,6 +138,18 @@ def _entries_from_toctree(toctreenode: addnodes.toctree, parents: List[str],
                         item = nodes.list_item('', para)
                         # don't show subitems
                         toc = nodes.bullet_list('', item)
+                    elif ref in ('genindex', 'modindex', 'search'):
+                        docname, _, sectionname = self.env.domains['std'].labels[ref]
+                        if not title:
+                            title = sectionname
+                        reference = nodes.reference('', '', internal=True,
+                                                    refuri=docname,
+                                                    anchorname='',
+                                                    *[nodes.Text(title)])
+                        para = addnodes.compact_paragraph('', '', reference)
+                        item = nodes.list_item('', para)
+                        # don't show subitems
+                        toc = nodes.bullet_list('', item)
                     else:
                         if ref in parents:
                             logger.warning(__('circular toctree references '

tests/roots/test-toctree-index/foo.rst

@@ -0,0 +1,8 @@
+foo
+===
+
+:index:`word`
+
+.. py:module:: pymodule
+
+.. py:function:: Timer.repeat(repeat=3, number=1000000)

tests/roots/test-toctree-index/index.rst

@@ -0,0 +1,15 @@
+test-toctree-duplicated
+=======================
+
+.. toctree::
+
+   foo
+
+
+.. toctree::
+   :caption: Indices
+
+   genindex
+   modindex
+   search
+

tests/test_environment_toctree.py

@@ -346,3 +346,18 @@ def test_get_toctree_for_includehidden(app):
 
     assert_node(toctree[2],
                 [bullet_list, list_item, compact_paragraph, reference, "baz"])
+
+
+@pytest.mark.sphinx('xml', testroot='toctree-index')
+@pytest.mark.test_params(shared_result='test_environment_toctree_basic')
+def test_toctree_index(app):
+    app.build()
+    toctree = app.env.tocs['index']
+    assert_node(toctree,
+                [bullet_list, ([list_item, (compact_paragraph,  # [0][0]
+                                            [bullet_list, (addnodes.toctree,  # [0][1][0]
+                                                           addnodes.toctree)])])])  # [0][1][1]
+    assert_node(toctree[0][1][1], addnodes.toctree,
+                caption="Indices", glob=False, hidden=False,
+                titlesonly=False, maxdepth=-1, numbered=0,
+                entries=[(None, 'genindex'), (None, 'modindex'), (None, 'search')])