From 175b14203798ddcc76a09882f54156ea31c43c9d Mon Sep 17 00:00:00 2001
From: Ashley Whetter <ashley@awhetter.co.uk>
Date: Fri, 7 May 2021 22:03:21 -0700
Subject: [PATCH] WIP domain nodes can be added to toc

Closes #6316
---
 sphinx/directives/__init__.py            |  2 ++
 sphinx/domains/cpp.py                    |  2 ++
 sphinx/domains/python.py                 |  3 +++
 sphinx/environment/collectors/toctree.py | 24 ++++++++++++++++++++++++
 4 files changed, 31 insertions(+)

diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py
index 8e8d65f0356..70f4195f47d 100644
--- a/sphinx/directives/__init__.py
+++ b/sphinx/directives/__init__.py
@@ -60,6 +60,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
     final_argument_whitespace = True
     option_spec: OptionSpec = {
         'noindex': directives.flag,
+        'toctree': directives.unchanged,
     }
 
     # types of doc fields that this directive handles, see sphinx.util.docfields
@@ -170,6 +171,7 @@ def run(self) -> List[Node]:
         # 'desctype' is a backwards compatible attribute
         node['objtype'] = node['desctype'] = self.objtype
         node['noindex'] = noindex = ('noindex' in self.options)
+        node['toctree'] = 'toctree' in self.options
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py
index 7bb1e49aae3..ac642b72195 100644
--- a/sphinx/domains/cpp.py
+++ b/sphinx/domains/cpp.py
@@ -6855,6 +6855,7 @@ class CPPObject(ObjectDescription[ASTDeclaration]):
 
     option_spec: OptionSpec = {
         'noindexentry': directives.flag,
+        'toctree': directives.unchanged,
         'tparam-line-spec': directives.flag,
     }
 
@@ -6945,6 +6946,7 @@ def add_target_and_index(self, ast: ASTDeclaration, sig: str,
             names = self.env.domaindata['cpp']['names']
             if name not in names:
                 names[name] = ast.symbol.docname
+                signode['displayname'] = ast.symbol.declaration.get_display_string()
             # always add the newest id
             assert newestId
             signode['ids'].append(newestId)
diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
index 4464895efa9..797ea1d7186 100644
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -360,6 +360,7 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
     option_spec: OptionSpec = {
         'noindex': directives.flag,
         'noindexentry': directives.flag,
+        'toctree': directives.unchanged,
         'module': directives.unchanged,
         'canonical': directives.unchanged,
         'annotation': directives.unchanged,
@@ -441,6 +442,7 @@ def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]
         signode['module'] = modname
         signode['class'] = classname
         signode['fullname'] = fullname
+        signode['displayname'] = name
 
         sig_prefix = self.get_signature_prefix(sig)
         if sig_prefix:
@@ -901,6 +903,7 @@ class PyModule(SphinxDirective):
         'platform': lambda x: x,
         'synopsis': lambda x: x,
         'noindex': directives.flag,
+        'toctree': directives.unchanged,
         'deprecated': directives.flag,
     }
 
diff --git a/sphinx/environment/collectors/toctree.py b/sphinx/environment/collectors/toctree.py
index 921fc83ded0..a8de9d50e68 100644
--- a/sphinx/environment/collectors/toctree.py
+++ b/sphinx/environment/collectors/toctree.py
@@ -111,6 +111,30 @@ def build_toc(node: Element, depth: int = 1) -> nodes.bullet_list:
                     if blist:
                         onlynode += blist.children
                         entries.append(onlynode)
+                elif isinstance(sectionnode, addnodes.desc):
+                    name = sectionnode.get('toctree')
+                    if name is False or not sectionnode.children:
+                        continue
+                    elif not name or name is True:
+                        name = sectionnode.children[0].get('displayname')
+
+                    # The user has not supplied a display name and neither has the node,
+                    # so we don't know how to display this.
+                    if not name:
+                        continue
+
+                    ref_id = sectionnode.children[0].attributes["ids"][0]
+                    nodetext = [nodes.Text(name, name)]
+                    reference = nodes.reference(
+                        '', '', internal=True, refuri=docname,
+                        anchorname='#' + ref_id, *nodetext,
+                    )
+                    para = addnodes.compact_paragraph('', '', reference)
+                    item: Element = nodes.list_item('', para)
+                    sub_item = build_toc(sectionnode, depth + 1)
+                    if sub_item:
+                        item += sub_item
+                    entries.append(item)
                 elif isinstance(sectionnode, nodes.Element):
                     for toctreenode in traverse_in_section(sectionnode,
                                                            addnodes.toctree):