#127 - Fix docs nav: consistent hide:navigation and data-driven tab dropdowns

docs/api-reference/python.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - navigation
+---
+
 # Python API Usage
 
 This guide covers Python initialization, RX/TX workflows, buffer lifecycle calls,

docs/benchmarks/benchmarks.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - navigation
+---
+
 # Benchmarking
 
 DAQIRI ships with several backends to handle different types of incoming and outgoing streams. Choosing the stream type depends on the type of sensor being used and its capabilities. The `stream_type` is decided from the decision tree below:

docs/benchmarks/raw_benchmarking.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - navigation
+---
+
 # Raw Ethernet Benchmarking
 
 DAQIRI provides raw Ethernet benchmark applications that use DPDK to drive an NVIDIA NIC directly. This page walks through `daqiri_bench_raw_gpudirect`, the TX/RX loopback config, and the raw Ethernet checks needed before interpreting throughput results.

docs/benchmarks/socket_benchmarking.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - navigation
+---
+
 # Socket and RDMA Benchmarking
 
 Use this page when the peer protocol is TCP, UDP, or RoCE/RDMA. These benchmarks use the Linux networking stack for TCP/UDP and RDMA verbs for RoCE, so the same client/server namespace shape is useful for proving that traffic leaves the host through the expected NIC path.

docs/javascripts/tab-dropdowns.js

@@ -4,24 +4,16 @@
 // without this script there's no way to hop directly between sibling
 // pages without bouncing through the section's index.
 //
-// Sub-page list is mirrored from `mkdocs.yml` nav. Keep them in sync when
-// adding/removing entries.
+// The section/sub-page list is NOT hand-maintained here: the
+// `hooks/nav_dropdowns.py` MkDocs hook serializes the real nav from
+// mkdocs.yml into `window.NV_NAV` at build time, so the dropdowns stay in
+// sync with the nav automatically. Each entry's `url` is already
+// site-root-relative (e.g. "api-reference/python/").
 
 (function () {
   "use strict";
 
-  const SECTIONS = {
-    "API Reference": [
-      { label: "API Guide",                    path: "api-reference/" },
-      { label: "Configuration YAML Reference", path: "api-reference/configuration/" },
-      { label: "C++ API Usage",                path: "api-reference/cpp/" }
-    ],
-    "Tutorials": [
-      { label: "System Configuration",          path: "tutorials/system_configuration/" },
-      { label: "Bare-Metal CMake Build",        path: "tutorials/bare-metal-cmake-build/" },
-      { label: "Configuration YAML Walkthrough", path: "tutorials/configuration-walkthrough/" }
-    ]
-  };
+  const SECTIONS = window.NV_NAV || {};
 
   function getSiteBase() {
     // Material's site logo link in the header always points to the site
@@ -56,7 +48,7 @@
       subpages.forEach((sub) => {
         const li = document.createElement("li");
         const a  = document.createElement("a");
-        a.href = base + sub.path;
+        a.href = base + sub.url;
         a.textContent = sub.label;
         li.appendChild(a);
         dd.appendChild(li);

docs/tutorials/bare-metal-cmake-build.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - navigation
+---
+
 # Bare-Metal CMake Build
 
 This tutorial walks you through a complete bare-metal DAQIRI build on a Linux host, from verifying the kernel, driver, NIC, and CUDA prerequisites, through building a patched DPDK from source, configuring DAQIRI with CMake, installing the library, and recovering from the most common failure modes.

hooks/nav_dropdowns.py

@@ -0,0 +1,37 @@
+"""Serialize the MkDocs nav into each page so the top-nav tab dropdowns can be
+built from a single source of truth.
+
+The sub-pages of several sections (Benchmarking, API Reference, Tutorials) hide
+the primary sidebar via `hide: navigation` front matter, so without an injected
+dropdown there is no way to hop between sibling pages. `docs/javascripts/
+tab-dropdowns.js` builds those dropdowns at runtime; this hook hands it the data
+derived directly from `mkdocs.yml` nav, so the two never drift.
+"""
+
+import json
+
+_NAV_JSON = "{}"
+
+
+def on_nav(nav, config, files):
+    """Capture multi-page sections from the built nav as {title: [{label, url}]}."""
+    global _NAV_JSON
+    sections = {}
+    for item in nav.items:
+        if not getattr(item, "is_section", False) or not item.children:
+            continue
+        subpages = [
+            {"label": child.title, "url": child.url}
+            for child in item.children
+            if getattr(child, "is_page", False) and child.title
+        ]
+        if len(subpages) > 1:
+            sections[item.title] = subpages
+    _NAV_JSON = json.dumps(sections)
+    return nav
+
+
+def on_post_page(output, page, config):
+    """Inject the captured nav as `window.NV_NAV` for tab-dropdowns.js to read."""
+    snippet = "<script>window.NV_NAV = {};</script>".format(_NAV_JSON)
+    return output.replace("</head>", snippet + "</head>", 1)

mkdocs.yml

@@ -96,5 +96,8 @@ validation:
     unrecognized_links: warn
     anchors: warn
 
+hooks:
+  - hooks/nav_dropdowns.py
+
 plugins:
   - search