WIP domain nodes can be added to toc

Closes sphinx-doc#6316

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

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)

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

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