[parashardhapola]

Use the guide header and navigation throughout the Sphinx API reference while preserving API content, links and native search.

Publish API output once, exclude internal search pages from indexing, and provide consistent canonical URLs, page titles and logo preview metadata.

Validation: documentation tests, strict Sphinx and MyST builds, lint, and browser checks for navigation, themes and metadata passed.

Requires the updated shared assets from the documentation hub.

[qodo-code-review]

PR Summary by Qodo

Unify API navigation and improve documentation discovery

✨ Enhancement 🧪 Tests 🕐 40+ Minutes

AI Description

• Give Sphinx API pages the guide’s header and navigation while preserving API content and native
 search.
• Publish API output once and improve canonical URLs, page titles, and sharing metadata.
• Exclude Sphinx search pages from indexing and test navigation and metadata behavior.

Diagram

graph TD
  API["Sphinx API"] --> Tree["API tree"] --> TOC["Staged TOC"] --> Guide["MyST guide"] --> Output["Combined output"] --> Discovery["Discovery metadata"] --> Navigation["Unified navigation"] --> Site["Published HTML"]
  API --> Output
  Guide --> Navigation

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Shared cross-theme navigation component

• ➕ Could avoid extracting and rewriting rendered HTML when either theme changes.
• ➖ Requires deeper integration between Sphinx and MyST themes and coordination with shared documentation assets.

Recommendation: The build-time approach is pragmatic: it leaves Sphinx API content and search intact while making navigation available in static HTML. Prefer it for this scope, with attention to its dependence on generated theme markup; a shared component becomes more attractive if additional documentation sites need the same integration.

Files changed (7) +573 / -47

Enhancement (3) +313 / -42

build_docs.pyCombine API and guide navigation in the publication build +277/-42

Combine API and guide navigation in the publication build

• Extracts Sphinx API links into the staged MyST table of contents, copies API output once, and inserts the rendered guide header and sidebar into API pages. Normalizes titles and sharing metadata, reuses navigation assets, and extends guarded theme patches.

docs/build_docs.py

docs-navigation.htmlExpose the Sphinx API tree for unified navigation +5/-0

Expose the Sphinx API tree for unified navigation

• Adds a sidebar template that renders the Sphinx API toctree in a discoverable navigation element.

docs/source/reference/api/_templates/docs-navigation.html

layout.htmlPrepare Sphinx pages for the guide header and theme +31/-0

Prepare Sphinx pages for the guide header and theme

• Adds a header placeholder, synchronizes the initial theme, and marks Sphinx search pages as non-indexable.

docs/source/reference/api/_templates/layout.html

Tests (2) +253 / -3

test_docs_render.pyTest API navigation integration and discovery metadata +251/-2

Test API navigation integration and discovery metadata

• Covers API links under root and prefixed URLs, preservation of API content and assets, navigation selection, and title and sharing-tag normalization. Adds failure cases for missing navigation and authored metadata.

tests/test_docs_render.py

test_docs_structure.pyAssert API output is not configured as a static file +2/-1

Assert API output is not configured as a static file

• Updates the documentation structure check to require removal of the former API static-files entry.

tests/test_docs_structure.py

Other (2) +7 / -2

myst.ymlStop publishing API output as a MyST static file +0/-1

Stop publishing API output as a MyST static file

• Removes the static-files entry for the Sphinx build because the publication script now copies that output directly.

docs/source/myst.yml

conf.pyConfigure Sphinx templates and shared page chrome +7/-1

Configure Sphinx templates and shared page chrome

• Enables the new templates and sidebar, adjusts article controls and footer content, and removes Sphinx navigation elements superseded by the guide navigation.

docs/source/reference/api/conf.py

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

1. Documentation builds reject the API index link 🐞 Bug ≡ Correctness

Description

include_api_navigation() requires every anchor in the Sphinx sidebar to end in .html, including
the current API index entry. When Sphinx renders that entry as href="#", the function raises
ValueError before the MyST build can start.

Code

docs/build_docs.py[R400-402]

+        href = unescape(href)
+        if urlsplit(href).scheme or href.startswith("//") or not href.endswith(".html"):
+            raise ValueError(f"Expected an API page link in {source}: {href}")

Evidence

The new sidebar renders the toctree on the API index, whose source lists the child pages. The
extraction loop processes every resulting anchor, while its new validation excludes Sphinx's
current-page fragment link; the extraction test supplies only .html anchors.

docs/source/reference/api/_templates/docs-navigation.html[1-5]
docs/source/reference/api/index.md[12-21]
docs/build_docs.py[392-411]
tests/test_docs_render.py[1455-1462]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`include_api_navigation()` rejects the API index's current-page `href="#"` link while extracting Sphinx's sidebar, stopping the documentation build.

## Fix Focus Areas
- docs/build_docs.py[397-409]
- tests/test_docs_render.py[1455-1462]

## Recommended Fix
Skip the current-page fragment link when extracting child API pages, or explicitly translate it to `/api/index.html`. Add a test whose sidebar includes the current-page link alongside the `.html` child links.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

---

2. Standalone API pages lose header navigation 🐞 Bug ≡ Correctness

Description

layout.html replaces the Sphinx navbar with an empty docs-header-placeholder rather than a
usable fallback. Running make check-reference builds the API without the later integration step,
leaving those directly built pages without the header menu or search trigger.

Code

docs/source/reference/api/_templates/layout.html[R27-30]

+{% block docs_navbar %}
+<header id="pst-header" class="bd-header myst-top-nav docs-api-top-nav">
+  <nav class="docs-header-placeholder"></nav>
+</header>

Evidence

The template contains only an empty navigation placeholder. The Makefile's standalone target invokes
Sphinx directly, whereas replacement of that placeholder happens only in the separate integration
function.

docs/source/reference/api/_templates/layout.html[27-30]
docs/Makefile[8-16]
docs/build_docs.py[476-487]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The custom navbar is empty until the separate MyST integration step runs, so pages produced by the standalone Sphinx target have no header menu or search trigger.

## Fix Focus Areas
- docs/source/reference/api/_templates/layout.html[27-30]
- docs/build_docs.py[476-482]

## Recommended Fix
Render a functional Sphinx navbar as the fallback in the custom layout, and have the integration step replace that fallback with the guide header for the published site. Check both the direct Sphinx output and the integrated output.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

---

Context sources

Review mode: Auto: ⚖️ Balanced: Downgraded extended -> standard: change is below the extended eligibility bar (hunks 17/18, lines 620/200; both must reach the floor). Router rationale: Substantial documentation pipeline logic spans navigation, metadata, builds, templates, and publishing.

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

1. Documentation builds reject the api index link 🐞 Bug ≡ Correctness

include_api_navigation() requires every anchor in the Sphinx sidebar to end in .html, including
the current API index entry. When Sphinx renders that entry as href="#", the function raises
ValueError before the MyST build can start.

Agent Prompt

## Issue description
`include_api_navigation()` rejects the API index's current-page `href="#"` link while extracting Sphinx's sidebar, stopping the documentation build.

## Fix Focus Areas
- docs/build_docs.py[397-409]
- tests/test_docs_render.py[1455-1462]

## Recommended Fix
Skip the current-page fragment link when extracting child API pages, or explicitly translate it to `/api/index.html`. Add a test whose sidebar includes the current-page link alongside the `.html` child links.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

[qodo-code-review]

2. Standalone api pages lose header navigation 🐞 Bug ≡ Correctness

layout.html replaces the Sphinx navbar with an empty docs-header-placeholder rather than a
usable fallback. Running make check-reference builds the API without the later integration step,
leaving those directly built pages without the header menu or search trigger.

Agent Prompt

## Issue description
The custom navbar is empty until the separate MyST integration step runs, so pages produced by the standalone Sphinx target have no header menu or search trigger.

## Fix Focus Areas
- docs/source/reference/api/_templates/layout.html[27-30]
- docs/build_docs.py[476-482]

## Recommended Fix
Render a functional Sphinx navbar as the fallback in the custom layout, and have the integration step replace that fallback with the guide header for the published site. Check both the direct Sphinx output and the integrated output.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗