Unify docs build into a single build, support proper multiversion links (#81)

* docs: unify sphinx build, fix multiversion links

* 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.

Co-authored-by: RyaliNvidia <[email protected]>

---------

Co-authored-by: RyaliNvidia <[email protected]>

Author: adelbertc

README.md

@@ -23,7 +23,7 @@ SPDX-License-Identifier: Apache-2.0
 ### Workflow Orchestration Purpose-built for Physical AI
 
 <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
-<a href="https://nvidia.github.io/OSMO/user_guide"><img src="https://img.shields.io/badge/docs-latest-brightgreen.svg" alt="Documentation"></a>
+<a href="https://nvidia.github.io/OSMO/main/user_guide"><img src="https://img.shields.io/badge/docs-latest-brightgreen.svg" alt="Documentation"></a>
 <a href="https://kubernetes.io/"><img src="https://img.shields.io/badge/Kubernetes-Native-326ce5.svg" alt="Kubernetes"></a>
 
 <a href="#ready-to-begin">Get Started</a>
@@ -116,13 +116,13 @@ OSMO solves this [Three Computer Problem](https://blogs.nvidia.com/blog/three-co
 
 | **What You Can Do** | **Example** |
 |---------------------|----------------------|
-| **Interactively develop** on remote GPU nodes with VSCode, SSH, or Jupyter notebooks | [Interactive Workflows](https://nvidia.github.io/OSMO/user_guide/main/workflows/interactive/index.html) |
-| **Generate synthetic data** at scale using Isaac Sim or custom simulation environments | [Isaac Sim SDG](https://nvidia.github.io/OSMO/user_guide/main/how_to/isaac_sim_sdg.html) |
-| **Train models** with diverse datasets across distributed GPU clusters | [Model Training](https://nvidia.github.io/OSMO/user_guide/main/how_to/training.html) |
-| **Train policies** for robots using data-parallel reinforcement learning | [Reinforcement Learning](https://nvidia.github.io/OSMO/user_guide/main/how_to/reinforcement_learning.html) |
-| **Validate models** in simulation with hardware-in-the-loop testing | [Hardware In The Loop](https://nvidia.github.io/OSMO/user_guide/main/tutorials/hardware_in_the_loop/index.html) |
-| **Transform and post-process data** for iterative improvement | [Working with Data](https://nvidia.github.io/OSMO/user_guide/main/tutorials/data/index.html) |
-| **Benchmark system software** on actual robot hardware (NVIDIA Jetson, custom platforms) | [Hardware Testing](https://nvidia.github.io/OSMO/user_guide/main/how_to/hil.html) |
+| **Interactively develop** on remote GPU nodes with VSCode, SSH, or Jupyter notebooks | [Interactive Workflows](https://nvidia.github.io/OSMO/main/user_guide/workflows/interactive/index.html) |
+| **Generate synthetic data** at scale using Isaac Sim or custom simulation environments | [Isaac Sim SDG](https://nvidia.github.io/OSMO/main/user_guide/how_to/isaac_sim_sdg.html) |
+| **Train models** with diverse datasets across distributed GPU clusters | [Model Training](https://nvidia.github.io/OSMO/main/user_guide/how_to/training.html) |
+| **Train policies** for robots using data-parallel reinforcement learning | [Reinforcement Learning](https://nvidia.github.io/OSMO/main/user_guide/how_to/reinforcement_learning.html) |
+| **Validate models** in simulation with hardware-in-the-loop testing | [Hardware In The Loop](https://nvidia.github.io/OSMO/main/user_guide/tutorials/hardware_in_the_loop/index.html) |
+| **Transform and post-process data** for iterative improvement | [Working with Data](https://nvidia.github.io/OSMO/main/user_guide/tutorials/data/index.html) |
+| **Benchmark system software** on actual robot hardware (NVIDIA Jetson, custom platforms) | [Hardware Testing](https://nvidia.github.io/OSMO/main/user_guide/how_to/hil.html) |
 
 ### Battle-Tested in Production
 
@@ -135,7 +135,7 @@ OSMO is production-grade and proven at scale. Originally developed to power Phys
 Select one of the deployment options below depending on your needs and environment to get started
 
 <div align="center">
-  <a href="https://nvidia.github.io/OSMO/deployment_guide/main/introduction/whats_next.html">
+  <a href="https://nvidia.github.io/OSMO/main/deployment_guide/introduction/whats_next.html">
     <img src="./docs/deployment_options.svg" width="85%"/>
   </a>
 </div>
@@ -146,11 +146,11 @@ Select one of the deployment options below depending on your needs and environme
 
 | Resource | Description |
 |:---------|:------------|
-| 🚀 [**Local Deployment**](https://nvidia.github.io/OSMO/deployment_guide/main/appendix/deploy_local.html) | Run it locally on your workstation in 10 minutes |
-| 🛠️ [**Cloud Deployment**](https://nvidia.github.io/OSMO/deployment_guide/) | Deploy production grade on cloud providers  |
-| 📘 [**User Guide**](https://nvidia.github.io/OSMO/user_guide/) | Tutorials, workflows, and how-to guides for developers |
+| 🚀 [**Local Deployment**](https://nvidia.github.io/OSMO/main/deployment_guide/appendix/deploy_local.html) | Run it locally on your workstation in 10 minutes |
+| 🛠️ [**Cloud Deployment**](https://nvidia.github.io/OSMO/main/deployment_guide/) | Deploy production grade on cloud providers  |
+| 📘 [**User Guide**](https://nvidia.github.io/OSMO/main/user_guide/) | Tutorials, workflows, and how-to guides for developers |
 | 💡 [**Workflow Examples**](./workflows/) | Robotics workflow examples
-| 💻 [**Getting Started**](https://nvidia.github.io/OSMO/user_guide/main/getting_started/install/index.html) | Install command-line interface to get started |
+| 💻 [**Getting Started**](https://nvidia.github.io/OSMO/main/user_guide/getting_started/install/index.html) | Install command-line interface to get started |
 
 ## Community & Support
 

deployments/charts/quick-start/README.md

@@ -22,7 +22,7 @@ This Helm chart provides a complete OSMO deployment for trying OSMO. If you are
 OSMO, this is a good way to get a feel for OSMO without deploying in a CSP.
 
 It is recommended to install this chart in a KIND cluster instead of a CSP. See
-[Local Deployment](https://nvidia.github.io/OSMO/deployment_guide/main/appendix/deploy_local.html) for
+[Local Deployment](https://nvidia.github.io/OSMO/main/deployment_guide/appendix/deploy_local.html) for
 detailed installation instructions.
 
 ## Prerequisites

deployments/charts/quick-start/templates/NOTES.txt

@@ -28,4 +28,4 @@
    osmo login http://quick-start.osmo --method=dev --username=testuser
 
 4. Explore next steps:
-   https://nvidia.github.io/OSMO/user_guide/getting_started/next_steps.html
+   https://nvidia.github.io/OSMO/main/user_guide/getting_started/next_steps.html

deployments/charts/web-ui/README.md

@@ -53,7 +53,7 @@ This Helm chart deploys the OSMO UI service along with its required sidecars and
 | `services.ui.hostAliases` | Host aliases for custom DNS resolution | `[]` |
 | `services.ui.tolerations` | Tolerations for pod scheduling on tainted nodes | `[]` |
 | `services.ui.resources` | Resource limits and requests for the UI container | `{}` |
-| `services.ui.docsBaseUrl` | Documentation base URL users will see from the UI | `"https://nvidia.github.io/OSMO/user_guide/"` |
+| `services.ui.docsBaseUrl` | Documentation base URL users will see from the UI | `"https://nvidia.github.io/OSMO/main/user_guide/"` |
 | `services.ui.cliInstallScriptUrl` | CLI Installation Script URL displayed in the UI | `"https://raw.githubusercontent.com/NVIDIA/OSMO/refs/heads/main/install.sh"` |
 
 ### UI Scaling Settings

deployments/charts/web-ui/values.yaml

@@ -115,7 +115,7 @@ services:
 
     ## Documentation base URL
     ##
-    docsBaseUrl: "https://nvidia.github.io/OSMO/user_guide/"
+    docsBaseUrl: "https://nvidia.github.io/OSMO/main/user_guide/"
 
     ## CLI Installation Script URL
     ##

docs/BUILD

@@ -20,52 +20,26 @@ load("@aspect_bazel_lib//lib:copy_to_directory.bzl", "copy_to_directory")
 
 package(default_visibility = ["//visibility:public"])
 
+# Build all documentation as a unified Sphinx project
 filegroup(
-    name = "root_docs_sources",
-    srcs = glob([
-        "_static/**",
-        "_extensions/**",
-        "conf.py",
-        "index.rst",
-    ]),
-)
-
-copy_to_directory(
-    name = "root_docs_copy",
-    srcs = [":root_docs_sources"],
-    out = "root_docs",
-)
-
-filegroup(
-    name = "user_guide_sources",
+    name = "all_docs_sources",
     srcs = glob([
         "_static/**",
         "_extensions/**",
         "_templates/**",
+        "_redirect/**",
         "user_guide/**",
-        "conf.py",
-    ]),
-)
-
-copy_to_directory(
-    name = "user_guide_copy",
-    srcs = [":user_guide_sources"],
-    out = "user_guide",
-)
-
-filegroup(
-    name = "deployment_guide_sources",
-    srcs = glob([
-        "_static/**",
-        "_extensions/**",
-        "_templates/**",
         "deployment_guide/**",
-        "conf.py",
+        "*.py",
+        "*.rst",
+        "*.svg",
+        "*.png",
+        "*.txt",
     ]),
 )
 
 copy_to_directory(
-    name = "deployment_guide_copy",
-    srcs = [":deployment_guide_sources"],
-    out = "deployment_guide",
+    name = "docs_copy",
+    srcs = [":all_docs_sources"],
+    out = "docs",
 )

docs/Makefile

@@ -35,50 +35,24 @@ clean:
 	rm -rf _build
 
 build:
-	export OSMO_DOMAIN=public && sphinx-build -b html . -w $(ERR_DIR)/root.log $(OUT_DIR)
-	export OSMO_DOMAIN=public && sphinx-build -b html user_guide -w $(ERR_DIR)/user_guide.log  $(OUT_DIR)/user_guide
-	export OSMO_DOMAIN=public && sphinx-build -b html deployment_guide -w $(ERR_DIR)/deployment_guide.log $(OUT_DIR)/deployment_guide
-	export OSMO_DOMAIN=public && sphinx-build -b markdown user_guide $(OUT_DIR)/user_guide -w $(ERR_DIR)/user_guide_markdown.log
-	export OSMO_DOMAIN=public && sphinx-build -b markdown deployment_guide $(OUT_DIR)/deployment_guide -w $(ERR_DIR)/deployment_guide_markdown.log
+	export OSMO_DOMAIN=public && sphinx-build -b html . -w $(ERR_DIR)/build.log $(OUT_DIR)
+	export OSMO_DOMAIN=public && sphinx-build -b markdown . -w $(ERR_DIR)/markdown.log $(OUT_DIR)
 	rm -rf $(OUT_DIR)/_sources
-	rm -rf $(OUT_DIR)/user_guide/_sources
-	rm -rf $(OUT_DIR)/deployment_guide/_sources
 
 build-multiversion:
-	export OSMO_DOMAIN=public && sphinx-build -b html . -w $(ERR_DIR)/root.log $(OUT_DIR)
-	export OSMO_DOMAIN=public && $(SPHINXBUILD) user_guide $(OUT_DIR)/user_guide
-	export OSMO_DOMAIN=public && $(SPHINXBUILD) deployment_guide $(OUT_DIR)/deployment_guide
+	export OSMO_DOMAIN=public && $(SPHINXBUILD) . $(OUT_DIR)
 	rm -rf $(OUT_DIR)/_sources
-	rm -rf $(OUT_DIR)/user_guide/_sources
-	rm -rf $(OUT_DIR)/deployment_guide/_sources
-	# Copy root redirect files
-	@cp _redirect/redirect_user_guide.html $(OUT_DIR)/user_guide/index.html
-	@cp _redirect/redirect_deployment_guide.html $(OUT_DIR)/deployment_guide/index.html
 
-build-root-html:
-	export OSMO_DOMAIN=public && sphinx-build -b html . -w $(ERR_DIR)/root.log $(OUT_DIR)
+build-html:
+	export OSMO_DOMAIN=public && sphinx-build -b html . -w $(ERR_DIR)/build.log $(OUT_DIR)
 	rm -rf $(OUT_DIR)/_sources
 
 
-build-user-html:
-	export OSMO_DOMAIN=public && sphinx-build -b html user_guide -w $(ERR_DIR)/user_guide.log  $(OUT_DIR)/user_guide
-	rm -rf $(OUT_DIR)/user_guide/_sources
-
-
-build-deployment-html:
-	export OSMO_DOMAIN=public && sphinx-build -b html deployment_guide -w $(ERR_DIR)/deployment_guide.log $(OUT_DIR)/deployment_guide
-	rm -rf $(OUT_DIR)/deployment_guide/_sources
-
-
 spelling:
-	export OSMO_DOMAIN=public && sphinx-build -b spelling -j auto -w $(ERR_DIR)/root.log -N . $(OUT_DIR)
-	export OSMO_DOMAIN=public && sphinx-build -b spelling -j auto -w $(ERR_DIR)/user_guide.log -N user_guide $(OUT_DIR)/user_guide
-	export OSMO_DOMAIN=public && sphinx-build -b spelling -j auto -w $(ERR_DIR)/deployment_guide.log -N deployment_guide $(OUT_DIR)/deployment_guide
+	export OSMO_DOMAIN=public && sphinx-build -b spelling -j auto -w $(ERR_DIR)/spelling.log -N . $(OUT_DIR)
 
 linkcheck:
 	export OSMO_DOMAIN=public && sphinx-build -b linkcheck -w $(ERR_DIR)/root.log . $(OUT_DIR)
-	export OSMO_DOMAIN=public && sphinx-build -b linkcheck -w $(ERR_DIR)/user_guide.log user_guide $(OUT_DIR)/user_guide
-	export OSMO_DOMAIN=public && sphinx-build -b linkcheck -w $(ERR_DIR)/deployment_guide.log deployment_guide $(OUT_DIR)/deployment_guide
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/_extensions/nvidia_theme_override.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Override NVIDIA theme's sidebar behavior to restore PyData defaults."""
+
+# Store the original suppress_sidebar_toctree before NVIDIA overrides it
+_original_suppress_sidebar_toctree = {}
+
+def capture_original_sidebar_logic(app, pagename, templatename, context, doctree):
+    """Capture PyData's original suppress_sidebar_toctree before NVIDIA overrides it."""
+    # Store whatever PyData theme set (or didn't set)
+    if pagename not in _original_suppress_sidebar_toctree:
+        _original_suppress_sidebar_toctree[pagename] = context.get("suppress_sidebar_toctree")
+
+def restore_original_sidebar_logic(app, pagename, templatename, context, doctree):
+    """Restore PyData's original suppress_sidebar_toctree after NVIDIA overrides it."""
+    # Restore the original value that PyData set
+    original_value = _original_suppress_sidebar_toctree.get(pagename)
+    if original_value is not None:
+        context["suppress_sidebar_toctree"] = original_value
+    elif "suppress_sidebar_toctree" in context:
+        # If PyData didn't set it, remove NVIDIA's override
+        del context["suppress_sidebar_toctree"]
+
+def setup(app):
+    # Run at priority 999 to capture PyData's value before NVIDIA (which runs at 1000)
+    app.connect("html-page-context", capture_original_sidebar_logic, priority=999)
+    
+    # Run at priority 1001 to restore after NVIDIA has overridden it (which runs at 1000)
+    app.connect("html-page-context", restore_original_sidebar_logic, priority=1001)
+    
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/_templates/sidebar-nav-bs.html

@@ -0,0 +1,30 @@
+{#
+SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: LicenseRef-NvidiaProprietary
+
+NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
+property and proprietary rights in and to this material, related
+documentation and any modifications thereto. Any use, reproduction,
+disclosure or distribution of this material and related documentation
+without an express license agreement from NVIDIA CORPORATION or
+its affiliates is strictly prohibited.
+#}
+{# modified from https://github.com/pydata/pydata-sphinx-theme/blob/v0.16.1/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-nav-bs.html #}
+{# see "PyData Sphinx Theme License" in the README #}
+{# further modified from nvidia-sphinx-theme==0.0.8 to remove startdepth=0 hardcode #}
+{# Displays the TOC-tree for all pages. #}
+<nav class="bd-docs-nav bd-links"
+     aria-label="{{ _('Table of Contents') }}">
+  <p class="bd-links__title" role="heading" aria-level="1">{{ _("Table of Contents") }}</p>
+  <div class="bd-toc-item navbar-nav">
+    {{- generate_toctree_html(
+      "sidebar",
+      show_nav_level=theme_show_nav_level | int,
+      maxdepth=theme_navigation_depth | int,
+      collapse=theme_collapse_navigation | tobool,
+      includehidden=theme_sidebar_includehidden | tobool,
+      titles_only=True
+      )
+    -}}
+  </div>
+</nav>

docs/conf.py

@@ -16,16 +16,12 @@
 
 # -- Path setup --------------------------------------------------------------
 
-import os
 import sys
+from pathlib import Path
 
-sys.path.insert(0, os.path.abspath('..'))
-sys.path.insert(0, os.path.abspath('.'))
-
-# Determine if we're building from a subdirectory or root
-# Use current working directory since subdir conf.py files import this file
-_cwd = os.getcwd()
-_is_subdir = os.path.basename(_cwd) in ['user_guide', 'deployment_guide']
+# Add the directory containing conf.py to the path so custom extensions can be found
+# This is important for sphinx-multiversion which runs from temporary directories
+sys.path.insert(0, str(Path(__file__).parent.resolve()))
 
 # -- Project information -----------------------------------------------------
 
@@ -59,6 +55,9 @@
     '_extensions.domain_config',
     '_extensions.html_translator_mixin',
     '_extensions.markdown_translator',
+    
+    # Theme extension
+    '_extensions.nvidia_theme_override',
 ]
 
 # Spelling
@@ -67,7 +66,7 @@
 ]
 spelling_show_suggestions = True
 spelling_warning = True
-spelling_word_list_filename = '../spelling_wordlist.txt'
+spelling_word_list_filename = 'spelling_wordlist.txt'
 
 # Linkcheck ignore
 linkcheck_ignore = [
@@ -106,14 +105,6 @@
     '**/*.in.rst',  # Ignore files that are embedded in other files
 ]
 
-# When building from root, exclude everything in subdirectories
-# The index files will still be parsed for TOC but won't build full pages
-if not _is_subdir:
-    exclude_patterns.extend([
-        'user_guide/**',
-        'deployment_guide/**',
-    ])
-
 suppress_warnings = [
     'toc.excluded',
 ]
@@ -128,22 +119,14 @@
 html_title = 'OSMO Documentation'
 html_show_sourcelink = False
 
-if _is_subdir:
-    html_favicon = '../_static/osmo_favicon.png'
-    html_logo = '../_static/nvidia-logo-horiz-rgb-wht-for-screen.png'
-    html_static_path = ['../_static']
-    templates_path = ['../_templates']
-    html_css_files_extra = []
-else:
-    html_favicon = '_static/osmo_favicon.png'
-    html_logo = '_static/nvidia-logo-horiz-rgb-wht-for-screen.png'
-    html_static_path = ['_static']
-    # Hide sidebar completely for root page
-    html_sidebars = {
-        "**": []
-    }
-    # Add custom CSS to hide sidebar and remove vertical bar
-    html_css_files_extra = ['css/root_page.css']
+html_favicon = '_static/osmo_favicon.png'
+html_logo = '_static/nvidia-logo-horiz-rgb-wht-for-screen.png'
+html_static_path = ['_static']
+templates_path = ['_templates']
+
+html_sidebars = {
+    "index": [],
+}
 
 html_theme_options = {
     "collapse_navigation": False,
@@ -168,10 +151,6 @@
     'https://cdn.jsdelivr.net/npm/glightbox/dist/css/glightbox.min.css',
 ]
 
-# Add extra CSS files for root page
-if 'html_css_files_extra' in dir() and html_css_files_extra:
-    html_css_files.extend(html_css_files_extra)
-
 # JavaScript files to include in the HTML output
 # Files are loaded in the order they appear in this list
 html_js_files = [
@@ -249,3 +228,6 @@
 smv_branch_whitelist = r'^main$|^release/.*$'
 smv_remote_whitelist = r'^origin$'
 smv_prefer_remote_refs = False
+
+# Latest version
+smv_latest_version = 'main'