Skip to content

Conversation

@adelbertc
Copy link
Contributor

@adelbertc adelbertc commented Nov 23, 2025

Description

  • Unify Sphinx build to build as one project instead of separate User Guide and Deployment Guide builds
  • Change hard-coded URLs to use Sphinx roles so the correct multiversion link can be interpolated at build time
  • Add some overrides to nvidia-sphinx-theme hardcodes to get the correct sidebar Table of Contents behavior after unifying the build and by extension the toctree

The goal of this change is to make the links in our docs version-aware after moving to multiversion docs in #40. Normally the way to do this is to reference roles like :doc: and :ref: instead of hard-coding URLs, but since we have cross-guide links we also have to unify the Sphinx build to make the builds aware of roles across all our docs.

NOTE: Our root README and similar docs still hard-code to main. I figure this is an acceptable tradeoff at not complicating the build to account for this. All links within the actual docs pages should be cromulent.

Issue #92

Checklist

  • I am familiar with the Contributing Guidelines.
  • New or existing tests cover these changes.
  • The documentation is up to date with these changes.

@adelbertc adelbertc force-pushed the adelbertc/multiversion-unified-build branch 3 times, most recently from dad0529 to 62cc8db Compare November 23, 2025 20:36
@adelbertc adelbertc marked this pull request as ready for review November 23, 2025 20:41
@adelbertc adelbertc requested a review from a team November 23, 2025 20:41
@adelbertc adelbertc mentioned this pull request Nov 23, 2025
2 tasks
@adelbertc adelbertc force-pushed the adelbertc/multiversion-unified-build branch from c7b55bb to 62cc8db Compare November 23, 2025 22:28
* Unify Sphinx build to build as one project instead
  of separate User Guide and Deployment Guide builds
* Change hard-coded URLs to use Sphinx roles so
  the correct multiversion link can be interpolated
  at build time

The goal of this change is to make the links in our docs
version-aware after moving to multiversion docs in
#40. Normally the
way to do this is to reference roles like `:doc:` and
`:ref:` instead of hard-coding URLs, but since we have
cross-guide links we also have to unify the Sphinx build
to make the builds aware of roles across all our docs.
@adelbertc adelbertc force-pushed the adelbertc/multiversion-unified-build branch from fec55a9 to d7dc32f Compare November 25, 2025 17:51
@adelbertc adelbertc merged commit 4ab0164 into main Nov 26, 2025
7 checks passed
@adelbertc adelbertc deleted the adelbertc/multiversion-unified-build branch November 26, 2025 17:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants