(app, doctree, docname)
Add domain objects to the toctree dynamically.

    This should be attached to the ``doctree-resolved`` event.
    This works by:

    * Finding each domain node (addnodes.desc)
    * Figuring out it's parent that will be in the toctree
         (nodes.section, or a previously added addnodes.desc)
    * Finding that parent in the TOC Tree based on it's ID
    * Taking that element in the TOC Tree,
      and finding it's parent that is a TOC Listing (nodes.bullet_list)
    * Adding the new TOC element for our specific node as a child of that nodes.bullet_list
        * This checks that bullet_list's last child,
        and checks that it is also a nodes.bullet_list,
        effectively nesting it under that element
Add domain objects to the toctree dynamically.
Add domain objects to the toctree dynamically .
def add_domain_to_toctree(app, doctree, docname):
    """
    Add domain objects to the toctree dynamically.

    This should be attached to the ``doctree-resolved`` event.
    This works by:

    * Finding each domain node (addnodes.desc)
    * Figuring out it's parent that will be in the toctree
         (nodes.section, or a previously added addnodes.desc)
    * Finding that parent in the TOC Tree based on it's ID
    * Taking that element in the TOC Tree,
      and finding it's parent that is a TOC Listing (nodes.bullet_list)
    * Adding the new TOC element for our specific node as a child of that nodes.bullet_list
        * This checks that bullet_list's last child,
        and checks that it is also a nodes.bullet_list,
        effectively nesting it under that element
    """
    toc = app.env.tocs[docname]
    for desc_node in doctree.traverse(addnodes.desc):
        try:
            ref_id = desc_node.children[0].attributes["ids"][0]
        except (KeyError, IndexError):
            # autodoc-style directives already add nodes to the toc.
            continue
        try:
            # Python domain object
            ref_text = desc_node[0].attributes["fullname"].split(".")[-1].split("(")[0]
        except (KeyError, IndexError):
            # TODO[eric]: Support other Domains and ways of accessing this data
            # Use `astext` for other types of domain objects
            ref_text = desc_node[0].astext().split(".")[-1].split("(")[0]
        # This is the actual object that will exist in the TOC Tree
        # Sections by default, and other Desc nodes that we've previously placed.
        parent_node = _traverse_parent(
            node=desc_node, objtypes=(addnodes.desc, nodes.section)
        )

        if parent_node:
            toc_reference = _get_toc_reference(parent_node, toc, docname)
            if toc_reference:
                # Get the last child of our parent's bullet list, this is where "we" live.
                toc_insertion_point = _traverse_parent(
                    toc_reference, nodes.bullet_list
                )[-1]
                # Ensure we're added another bullet list so that we nest inside the parent,
                # not next to it
                if len(toc_insertion_point) > 1 and isinstance(
                    toc_insertion_point[1], nodes.bullet_list
                ):
                    to_add = _build_toc_node(docname, anchor=ref_id, text=ref_text)
                    toc_insertion_point = toc_insertion_point[1]
                else:
                    to_add = _build_toc_node(
                        docname,
                        anchor=ref_id,
                        text=ref_text,
                        bullet=True,
                    )
                toc_insertion_point.append(to_add)
def add_domain_to_toctree ( app , doctree , docname ) : toc = app . env . tocs [ docname ] for desc_node in doctree . traverse ( addnodes . desc ) : try : ref_id = desc_node . children [ 0 ] . attributes [ "ids" ] [ 0 ] except ( KeyError , IndexError ) : # autodoc-style directives already add nodes to the toc. continue try : # Python domain object ref_text = desc_node [ 0 ] . attributes [ "fullname" ] . split ( "." ) [ - 1 ] . split ( "(" ) [ 0 ] except ( KeyError , IndexError ) : # TODO[eric]: Support other Domains and ways of accessing this data # Use `astext` for other types of domain objects ref_text = desc_node [ 0 ] . astext ( ) . split ( "." ) [ - 1 ] . split ( "(" ) [ 0 ] # This is the actual object that will exist in the TOC Tree # Sections by default, and other Desc nodes that we've previously placed. parent_node = _traverse_parent ( node = desc_node , objtypes = ( addnodes . desc , nodes . section ) ) if parent_node : toc_reference = _get_toc_reference ( parent_node , toc , docname ) if toc_reference : # Get the last child of our parent's bullet list, this is where "we" live. toc_insertion_point = _traverse_parent ( toc_reference , nodes . bullet_list ) [ - 1 ] # Ensure we're added another bullet list so that we nest inside the parent, # not next to it if len ( toc_insertion_point ) > 1 and isinstance ( toc_insertion_point [ 1 ] , nodes . bullet_list ) : to_add = _build_toc_node ( docname , anchor = ref_id , text = ref_text ) toc_insertion_point = toc_insertion_point [ 1 ] else : to_add = _build_toc_node ( docname , anchor = ref_id , text = ref_text , bullet = True , ) toc_insertion_point . append ( to_add )