Merge branch 'master' into admin-guide-nav-restructure

Author: cwarnermm

extensions/sphinx_inline_tabs/events.py

@@ -1,8 +1,7 @@
 """
 Sphinx event handler implementation.
 """
-
-from typing import Any, Final, Optional
+from typing import Any, Final, Optional, Iterator, cast
 
 from docutils import nodes
 from sphinx import addnodes
@@ -74,20 +73,42 @@ def doctree_read(app: Sphinx, doctree: nodes.document):
     tab_docnames: list[str] = getattr(app.env, INLINE_TAB_DOCNAMES)
     if app.env.docname in tab_docnames:
         logger.debug(f"{LOG_PREFIX} doctree_read: {app.env.docname} has tabs")
+        logger.debug(
+            f"{LOG_PREFIX} doctree_read({app.env.docname}): app.env.tocs[app.env.docname]={app.env.tocs[app.env.docname]}"
+        )
+      
+        # check if this toc has a toctree node. if so, get a reference to it
+        toctree_nodes: Iterator[addnodes.toctree] = app.env.tocs[app.env.docname].findall(addnodes.toctree)
+        toctree_node: Optional[addnodes.toctree] = None
+        for node in toctree_nodes:
+            if node is not None and toctree_node is None:
+                toctree_node = node
+                logger.debug(f"{LOG_PREFIX} doctree_read: {app.env.docname} has a toctree node: {node}")
+                break
 
         # Generate the tab-based TOC (includes headings from within tabs)
         updated_tocs: nodes.list_item = sectiondata_to_toc(
             app.env.docname,
             collect_sections(app.env, doctree, app.env.docname, doctree),
         )
-            
+        
+        # if there was a toctree node, insert it at the start of the updated toc nodes
+        if toctree_node is not None:
+            toctree_bullet_list: nodes.bullet_list = nodes.bullet_list()
+            toctree_bullet_list.append(toctree_node)
+            for child_list in cast("nodes.Element", updated_tocs[1]).children:
+                toctree_bullet_list.append(child_list)
+            updated_tocs[1] = toctree_bullet_list
+        
+        # ensure the new toctree is a child of a bullet list
+        tocs_bullet_list: nodes.bullet_list = nodes.bullet_list()
+        tocs_bullet_list.append(updated_tocs)
         logger.debug(
-            f"{LOG_PREFIX} doctree_read({app.env.docname}): updated_tocs[0][1]={updated_tocs}"
+            f"{LOG_PREFIX} doctree_read({app.env.docname}): tocs_bullet_list={tocs_bullet_list}"
         )
-        if len(app.env.tocs[app.env.docname][0]) == 1:
-            app.env.tocs[app.env.docname][0].append(updated_tocs)
-        else:
-            app.env.tocs[app.env.docname][0][1] = updated_tocs
+        
+        # replace the document's toc with the one we just generated
+        app.env.tocs[app.env.docname] = tocs_bullet_list
 
 
 def html_page_context(
@@ -328,11 +349,12 @@ def sectiondata_to_toc(docname: str, secdata: SectionData) -> nodes.list_item:
     # Add a reference for this section (including tabs and regular sections)
     # Only skip adding reference if this is a section root with no meaningful name
     if secdata.name and not (secdata.is_section_root and secdata.name == secdata.id):
+        section_id: str = "" if secdata.level == 1 and secdata.tab_counter == 0 else secdata.id
         logger.debug(
             f"{LOG_PREFIX} sectiondata_to_toc(): "
-            f"({docname}): [{secdata.level}/{secdata.tab_counter}] add reference for {secdata.name}<{secdata.id}>"
+            f"({docname}): [{secdata.level}/{secdata.tab_counter}] add reference for {secdata.name}<{secdata.id}>: {section_id}"
         )
-        list_item.append(make_compact_reference(secdata.id, secdata.name, docname))
+        list_item.append(make_compact_reference(section_id, secdata.name, docname))
 
     if len(secdata.children) > 0:
         logger.debug(
@@ -369,7 +391,7 @@ def make_compact_reference(
             "",
             section_name,
             refuri=docname,
-            anchorname=f"#{section_id}",
+            anchorname=f"#{section_id}" if section_id else "",
             internal=True,
         )
     )