Workaround for Broken TOC Navigation

source/_extensions/sphinx_toctreeish.py

@@ -0,0 +1,68 @@
+import re
+from typing import List
+
+from docutils import nodes
+from docutils.nodes import Node
+from docutils.statemachine import StringList, ViewList
+
+import sphinx
+from sphinx import addnodes
+from sphinx.directives.other import TocTree
+
+
+class TocTreeish(TocTree):
+    def run(self) -> List[Node]:
+        assert self.options.get("hidden", False) == False
+
+        rootln = nodes.bullet_list()
+
+        delme = []
+        for entry in self.content:
+            node = addnodes.compact_paragraph()
+
+            if re.search(r"\s", entry):
+                if entry.startswith("_ "):
+                    # Raw syntax: parse...
+                    tmp = nodes.paragraph()
+                    self.state.nested_parse(ViewList([entry[2:]]), 0, tmp)
+
+                    # ... rip out the parsed thing into a compact paragraph...
+                    node += tmp.children[0].children
+
+                    # ... and prevent the real toctree from seeing it
+                    delme += [entry]
+                else:
+                    assert False, "TocTreeish doesn't understand spaced things"
+            elif entry == "self":
+                assert False, "TocTreeish doesn't do 'self'"
+            else:
+                # Single word, must be a doc xref.  Fake one up!
+                pxr = addnodes.pending_xref(
+                    entry,
+                    reftype="doc",
+                    refdomain="std",
+                    refexplicit=False,
+                    reftarget=entry,
+                )
+                pxr += nodes.inline("", entry, classes="xref std std-doc")
+                node += pxr
+
+            rootln.children += nodes.bullet_list("", nodes.list_item("", node))
+
+        for d in delme:
+            self.content.remove(d)
+
+        self.options["hidden"] = True
+        res = super().run()
+
+        # Push our list into the wrapper that still gets generated despite
+        # setting the toctree to hidden.
+        wrappernode = res[-1]
+        wrappernode.append(rootln)
+
+        return res
+
+
+def setup(app):
+    app.add_directive("toctreeish", TocTreeish)
+    return {"version": "1", "parallel_read_safe": True}

source/conf.py

@@ -10,9 +10,11 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("./_extensions/"))
 
 
 # -- Project information -----------------------------------------------------
@@ -45,6 +47,7 @@
     "notfound.extension",
     "versionwarning.extension",
     "sphinx_panels",
+    "sphinx_toctreeish",
 ]
 
 versionwarning_messages = {

source/docs/software/wpilib-tools/robot-simulation/index.rst

@@ -1,15 +1,17 @@
+.. Usage of toctreeish is due to https://github.com/sphinx-doc/sphinx/issues/701
+
 Robot Simulation
 ================
 
-.. toctree::
+.. toctreeish::
    :maxdepth: 1
 
    introduction
    simulation-gui
-   /docs/software/wpilib-tools/glass/widgets
-   /docs/software/wpilib-tools/glass/command-based-widgets
-   /docs/software/wpilib-tools/glass/field2d-widget
-   /docs/software/wpilib-tools/glass/plots
+   _ :ref:`Widgets <docs/software/wpilib-tools/glass/widgets:Glass Widgets>`
+   _ :ref:`Widgets for the Command-Based Framework <docs/software/wpilib-tools/glass/command-based-widgets:Widgets for the Command-Based Framework>`
+   _ :ref:`The Field2d Widget <docs/software/wpilib-tools/glass/field2d-widget:The Field2d Widget>`
+   _ :ref:`Plots <docs/software/wpilib-tools/glass/plots:Plots>`
    physics-sim
    device-sim
    unit-testing