From bb3437121a6c5655e4c3670d9530a76832d49a01 Mon Sep 17 00:00:00 2001 From: Ramya Gurunathan Date: Mon, 8 Jun 2026 09:49:22 -0400 Subject: [PATCH] #127 - Fix docs nav: consistent hide:navigation and data-driven tab dropdowns Five pages lacked the `hide: navigation` front matter their siblings carry, which left a stray sidebar on the Python API page. Add it to all five for consistency. The top-nav tab dropdowns were hand-mirrored from mkdocs.yml in tab-dropdowns.js and had drifted (missing the Python API Usage entry, no Benchmarking section). Replace the hardcoded map with a MkDocs hook (hooks/nav_dropdowns.py) that serializes the real nav into window.NV_NAV at build time, so the dropdowns stay in sync with mkdocs.yml automatically. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Ramya Gurunathan --- docs/api-reference/python.md | 5 ++++ docs/benchmarks/benchmarks.md | 5 ++++ docs/benchmarks/raw_benchmarking.md | 5 ++++ docs/benchmarks/socket_benchmarking.md | 5 ++++ docs/javascripts/tab-dropdowns.js | 22 +++++--------- docs/tutorials/bare-metal-cmake-build.md | 5 ++++ hooks/nav_dropdowns.py | 37 ++++++++++++++++++++++++ mkdocs.yml | 3 ++ 8 files changed, 72 insertions(+), 15 deletions(-) create mode 100644 hooks/nav_dropdowns.py diff --git a/docs/api-reference/python.md b/docs/api-reference/python.md index 3936b95..5ecc195 100644 --- a/docs/api-reference/python.md +++ b/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, diff --git a/docs/benchmarks/benchmarks.md b/docs/benchmarks/benchmarks.md index c8dc400..505b581 100644 --- a/docs/benchmarks/benchmarks.md +++ b/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: diff --git a/docs/benchmarks/raw_benchmarking.md b/docs/benchmarks/raw_benchmarking.md index a91c70e..712b0f0 100644 --- a/docs/benchmarks/raw_benchmarking.md +++ b/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. diff --git a/docs/benchmarks/socket_benchmarking.md b/docs/benchmarks/socket_benchmarking.md index eb6731c..a705a85 100644 --- a/docs/benchmarks/socket_benchmarking.md +++ b/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. diff --git a/docs/javascripts/tab-dropdowns.js b/docs/javascripts/tab-dropdowns.js index aa5de0a..a9aa266 100644 --- a/docs/javascripts/tab-dropdowns.js +++ b/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); diff --git a/docs/tutorials/bare-metal-cmake-build.md b/docs/tutorials/bare-metal-cmake-build.md index d1bfaba..a5650f5 100644 --- a/docs/tutorials/bare-metal-cmake-build.md +++ b/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. diff --git a/hooks/nav_dropdowns.py b/hooks/nav_dropdowns.py new file mode 100644 index 0000000..611fbfd --- /dev/null +++ b/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 = "".format(_NAV_JSON) + return output.replace("", snippet + "", 1) diff --git a/mkdocs.yml b/mkdocs.yml index 5c5c4b4..2d571a4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -96,5 +96,8 @@ validation: unrecognized_links: warn anchors: warn +hooks: + - hooks/nav_dropdowns.py + plugins: - search