Fixes cpp docs navbar rendering as a bulleted list

pytorch_sphinx_theme2/__init__.py

@@ -321,9 +321,8 @@ def _get_toctree_children(app, docname):
 def _cache_root_toctree_entries(app, doctree):
     """Cache toctree entries from the root doc during the read phase.
 
-    Called via doctree-read (not doctree-resolved) so this runs in the main
-    process before parallel write workers are spawned. The cached data on
-    app.env gets pickled and distributed to all workers.
+    Called via doctree-read (not doctree-resolved) so this runs before the
+    write phase, even when builders skip writing doctrees to disk.
     """
     docname = app.env.docname
     if docname != app.config.root_doc:
@@ -341,6 +340,19 @@ def _cache_root_toctree_entries(app, doctree):
     app.env._root_toctree_entries = entries
 
 
+def _merge_root_toctree_entries(app, env, docnames, other):
+    """Merge cached root toctree entries from a parallel-read worker env.
+
+    With sphinx-build -j, doctree-read fires in worker processes; custom
+    attributes set on the worker's env are not preserved unless we copy them
+    here. Without this, _root_toctree_entries stays empty in the main env
+    and the navbar falls back to generate_header_nav_html().
+    """
+    other_entries = getattr(other, "_root_toctree_entries", None)
+    if other_entries:
+        env._root_toctree_entries = other_entries
+
+
 def _get_toctree_entries_from_doctree(app, docname):
     """Get all toctree entries from a document, including external URLs.
 
@@ -476,6 +488,9 @@ def setup(app):
     # Cache root doc toctree entries during read phase (before doctrees may be
     # discarded by builders that skip disk writes for performance)
     app.connect("doctree-read", _cache_root_toctree_entries)
+    # With parallel reads (sphinx-build -j), doctree-read fires in workers;
+    # merge the cached entries back into the main env.
+    app.connect("env-merge-info", _merge_root_toctree_entries)
 
     # Add hierarchical navigation context for dropdown menus
     app.connect("html-page-context", _add_hierarchical_nav_to_context)

pytorch_sphinx_theme2/static/css/theme.css

@@ -3051,6 +3051,10 @@ nav.bd-links li > a {
   color: var(--pst-color-text-base) !important;
 }
 
+.page-toc .section-nav {
+  display: block;
+}
+
 .toc-entry a.nav-link, .toc-entry a > code {
   color: var(--pst-color-text-base) !important;
 }

pytorch_sphinx_theme2/static/scss/_custom.scss

@@ -158,11 +158,20 @@ nav.bd-links li>a {
   color: var(--pst-color-text-base) !important;
 }
 
-// Make right nav links more readable
+// Make right nav links more readable with compact padding
 .toc-entry a.nav-link, .toc-entry a>code {
   color: var(--pst-color-text-base) !important;
 }
 
+.page-toc .section-nav {
+  display: block;
+}
+
+.bd-sidebar-secondary .toc-entry a.nav-link {
+  padding-top: 0.125rem;
+  padding-bottom: 0.125rem;
+}
+
 .bd-sidebar-primary {
   width: 15%;
   min-width: 200px;

pytorch_sphinx_theme2/static/scss/_layout.scss

@@ -1,6 +1,12 @@
 // Layout styles
 @use 'variables';
 
+// Prevent navbar items from rendering as a bulleted list when <li> elements
+// appear outside a proper <ul> (e.g. C++ docs with Breathe/Doxygen builds)
+.navbar-header-items__center .navbar-item li.nav-item {
+  list-style: none;
+}
+
 // Header positioning
 .bd-header {
   top: var(--header-height-desktop) !important;

pytorch_sphinx_theme2/templates/navbar-nav.html

@@ -92,6 +92,13 @@
   </ul>
 </nav>
 {% else %}
-{# Fallback: use the default header navigation if hierarchical nav is empty #}
-{{ generate_header_nav_html()|safe }}
+{# Fallback: use the default header navigation if hierarchical nav is empty.
+   Wrap in <nav><ul> because generate_header_nav_html() returns only inner <li>
+   markup; without this wrapper, browsers render the bare <li>s with default
+   list-item bullets. #}
+<nav>
+  <ul class="bd-navbar-elements navbar-nav">
+    {{ generate_header_nav_html()|safe }}
+  </ul>
+</nav>
 {% endif %}