docs: unify sphinx build, fix multiversion links

adelbertc · adelbertc · commit 62cc8db6e32c · 2025-11-23T12:28:39.000-08:00
* 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.
diff --git a/README.md b/README.md
@@ -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/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/how_to/isaac_sim_sdg.html) |
-| **Train models** with diverse datasets across distributed GPU clusters | [Model Training](https://nvidia.github.io/OSMO/user_guide/how_to/training.html) |
+| **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/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/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/tutorials/data/index.html) |
-| **Benchmark system software** on actual robot hardware (NVIDIA Jetson, custom platforms) | [Hardware Testing](https://nvidia.github.io/OSMO/user_guide/how_to/hil.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) |
 
 ### Battle-Tested in Production
 
@@ -150,7 +150,7 @@ Select one of the deployment options below depending on your needs and environme
 | 🛠️ [**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 |
 | 💡 [**Workflow Examples**](./workflows/) | Robotics workflow examples
-| 💻 [**Getting Started**](https://nvidia.github.io/OSMO/user_guide/getting_started/install/index.html) | Install command-line interface to get started |
+| 💻 [**Getting Started**](https://nvidia.github.io/OSMO/user_guide/main/getting_started/install/index.html) | Install command-line interface to get started |
 
 ## Community & Support
 
diff --git a/deployments/charts/quick-start/templates/NOTES.txt b/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/user_guide/main/getting_started/next_steps.html
diff --git a/docs/BUILD b/docs/BUILD
@@ -20,53 +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",
-        "docs_options.svg",
-    ]),
-)
-
-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",
 )
diff --git a/docs/Makefile b/docs/Makefile
@@ -35,45 +35,21 @@ 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)
 
 
 # Catch-all target: route all unknown targets to Sphinx using the new
diff --git a/docs/conf.py b/docs/conf.py
@@ -67,7 +67,7 @@
 ]
 spelling_show_suggestions = True
 spelling_warning = True
-spelling_word_list_filename = '../spelling_wordlist.txt'
+spelling_word_list_filename = '../spelling_wordlist.txt' if _is_subdir else 'spelling_wordlist.txt'
 
 # Copybutton
 copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
@@ -90,13 +90,8 @@
     '**/*.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/**',
-    ])
+# Build everything as one unified Sphinx project
+# (previously excluded subdirectories when building from root)
 
 suppress_warnings = [
     'toc.excluded',
diff --git a/docs/deployment_guide/advanced_config/dataset_buckets.rst b/docs/deployment_guide/advanced_config/dataset_buckets.rst
@@ -21,8 +21,7 @@
 Dataset Buckets
 ===============
 
-Register external cloud storage buckets (S3, GCS, Azure) with OSMO to organize `datasets <https://nvidia.github.io/OSMO/user_guide/tutorials/data/index.html#datasets>`_ across multiple storage locations (This configuration is optional)
-
+Register external cloud storage buckets (S3, GCS, Azure) with OSMO to organize :ref:`datasets <tutorials_working_with_data_datasets>` across multiple storage locations (This configuration is optional)
 
 Why Use Dataset Buckets?
 =========================
@@ -310,4 +309,4 @@ Troubleshooting
 
 .. seealso::
 
-  - Learn more about datasets in OSMO at `Datasets <https://nvidia.github.io/OSMO/user_guide/tutorials/data/index.html#datasets>`_
+  - Learn more about datasets in OSMO at :ref:`Datasets <tutorials_working_with_data_datasets>`
diff --git a/docs/deployment_guide/advanced_config/rsync.rst b/docs/deployment_guide/advanced_config/rsync.rst
@@ -255,4 +255,4 @@ Troubleshooting
 
 .. seealso::
 
-  - Learn more about Rsync in OSMO at `Interactive Workflows <https://nvidia.github.io/OSMO/user_guide/workflows/interactive/rsync.html>`_
+  - Learn more about Rsync in OSMO at :doc:`Interactive Workflows </user_guide/workflows/interactive/rsync>`
diff --git a/docs/deployment_guide/advanced_config/scheduler.rst b/docs/deployment_guide/advanced_config/scheduler.rst
@@ -243,4 +243,4 @@ Troubleshooting
 .. seealso::
 
   - Learn more about `KAI scheduler <https://github.com/NVIDIA/kai-scheduler>`_
-  - Learn more about `scheduling in OSMO <https://nvidia.github.io/OSMO/user_guide/resource_pools/scheduling/index.html#scheduling>`_
+  - Learn more about :ref:`scheduling in OSMO <concepts_priority>`
diff --git a/docs/deployment_guide/appendix/deploy_local.rst b/docs/deployment_guide/appendix/deploy_local.rst
@@ -340,7 +340,7 @@ Next Steps
 
 Now that you have OSMO running locally, explore the platform:
 
-1. **Run Your First Workflow**: Visit the `User Guide <https://nvidia.github.io/OSMO/user_guide/getting_started/next_steps.html>`_ for tutorials on submitting workflows, interactive development, distributed training, and more.
+1. **Run Your First Workflow**: Visit the :doc:`User Guide </user_guide/getting_started/next_steps>` for tutorials on submitting workflows, interactive development, distributed training, and more.
 
 2. **Explore the Web UI**: Visit ``http://quick-start.osmo`` to access the OSMO dashboard.
 
diff --git a/docs/deployment_guide/appendix/workflow_execution.rst b/docs/deployment_guide/appendix/workflow_execution.rst
@@ -232,7 +232,7 @@ Learn More
 
 .. seealso::
 
-   - `Workflow Overview <https://nvidia.github.io/OSMO/user_guide/workflows/index.html>`__ - User guide for writing workflows
-   - `Workflow Lifecycle <https://nvidia.github.io/OSMO/user_guide/workflows/lifecycle/index.html>`__ - Understanding workflow states
+   - :doc:`Workflow Overview </user_guide/workflows/index>` - User guide for writing workflows
+   - :doc:`Workflow Lifecycle </user_guide/workflows/lifecycle/index>` - Understanding workflow states
    - :ref:`architecture` - Overall OSMO system architecture
 
diff --git a/docs/deployment_guide/index.rst b/docs/deployment_guide/index.rst
@@ -67,7 +67,7 @@ Integrate with your existing storage infrastructure:
 
 .. seealso::
 
-   Learn more about OSMO in the `What is OSMO? <https://nvidia.github.io/OSMO/user_guide/index.html#what-is-osmo>`_ section of the User Guide.
+   Learn more about OSMO in the :doc:`Welcome to OSMO </user_guide/index>` section of the User Guide.
 
 What You'll Deploy
 ==================
diff --git a/docs/deployment_guide/install_backend/dependencies/dependencies.rst b/docs/deployment_guide/install_backend/dependencies/dependencies.rst
@@ -34,7 +34,7 @@ Install Dependencies
 Install KAI Scheduler
 ======================
 
-OSMO uses `KAI scheduler <https://github.com/NVIDIA/kai-scheduler>`_ to run AI workflows at very large scale with `Workflow Groups <http://nvidia.github.io/OSMO/user_guide/tutorials/parallel_workflows/index.html#groups>`_.
+OSMO uses `KAI scheduler <https://github.com/NVIDIA/kai-scheduler>`_ to run AI workflows at very large scale with :ref:`Workflow Groups <tutorials_parallel_workflows_groups>`.
 
 For more information on the scheduler, see :ref:`scheduler`.
 
diff --git a/docs/deployment_guide/install_backend/deploy_backend.rst b/docs/deployment_guide/install_backend/deploy_backend.rst
@@ -26,7 +26,7 @@ Deploying the backend operator will register your compute backend with OSMO, mak
 .. admonition:: Prerequisites
   :class: important
 
-  - Install `OSMO CLI <https://nvidia.github.io/OSMO/user_guide/getting_started/install>`_ before you begin
+  - Install :doc:`OSMO CLI </user_guide/getting_started/install/index>` before you begin
   - Replace ``osmo.example.com`` with your domain name in the commands below
 
 .. _create_osmo_token:
diff --git a/docs/deployment_guide/install_backend/observability.rst b/docs/deployment_guide/install_backend/observability.rst
@@ -83,7 +83,7 @@ Next, update your OSMO backend configuration to include the Grafana and Kubernet
   $ osmo config update BACKEND $BACKEND_NAME --file /tmp/backend_config.json
 
 
-Once configured, you can access dashboard and resource usage links for each workflow in the OSMO UI. See the `Workflow Resource Usage <https://nvidia.github.io/OSMO/user_guide/faq/index.html#how-to-determine-the-resource-usage-of-a-workflow>`__ for details.
+Once configured, you can access dashboard and resource usage links for each workflow in the OSMO UI. See the :ref:`Workflow Resource Usage <faq_workflow_resource_usage>` for details.
 
 
 Security Considerations
diff --git a/docs/deployment_guide/requirements/system_reqs.rst b/docs/deployment_guide/requirements/system_reqs.rst
@@ -15,7 +15,7 @@
 
   SPDX-License-Identifier: Apache-2.0
 
-.. _system_requirements:
+.. _deployment_guide_system_requirements:
 
 ====================
 Instances
diff --git a/docs/deployment_guide/requirements/tools.rst b/docs/deployment_guide/requirements/tools.rst
@@ -49,7 +49,8 @@ Tools
           Required for database initialization and management tasks.
 
       .. grid-item-card:: :octicon:`file-code` OSMO Client
-          :link: https://nvidia.github.io/OSMO/user_guide/getting_started/install
+          :link: ../../user_guide/getting_started/install/index
+          :link-type: doc
           :class-card: tool-card
 
           OSMO client.
diff --git a/docs/deployment_options.svg b/docs/deployment_options.svg
@@ -116,7 +116,7 @@
   </defs>
 
   <!-- Card 1: Local Deployment -->
-  <a href="https://nvidia.github.io/OSMO/deployment_guide/appendix/deploy_local.html" class="card-link">
+  <a href="../appendix/deploy_local.html" class="card-link">
     <g id="card-local">
       <rect class="card-bg" x="30" y="30" width="360" height="740" rx="8"/>
       
@@ -149,7 +149,7 @@
   </a>
 
   <!-- Card 2: Minimal Deployment -->
-  <a href="https://nvidia.github.io/OSMO/deployment_guide/appendix/deploy_minimal.html" class="card-link">
+  <a href="../appendix/deploy_minimal.html" class="card-link">
     <g id="card-minimal">
       <rect class="card-bg" x="420" y="30" width="360" height="740" rx="8"/>
       
@@ -182,7 +182,7 @@
   </a>
 
   <!-- Card 3: Production Deployment -->
-  <a href="https://nvidia.github.io/OSMO/deployment_guide/requirements/prereqs.html" class="card-link">
+  <a href="../requirements/prereqs.html" class="card-link">
     <g id="card-production">
       <rect class="card-bg" x="810" y="30" width="360" height="740" rx="8"/>
       
diff --git a/docs/index.rst b/docs/index.rst
@@ -30,3 +30,9 @@ Select one of the guides below to get started with OSMO.
 
   .. raw:: html
      :file: docs_options.svg
+
+.. toctree::
+   :hidden:
+
+   deployment_guide/index
+   user_guide/index
diff --git a/docs/user_guide/architecture.rst b/docs/user_guide/architecture.rst
@@ -354,4 +354,4 @@ deployments while maintaining a consistent interface and workflow experience.
 
 .. seealso::
 
-  For detailed deployment procedures, refer to the `Deployment Guide <https://nvidia.github.io/OSMO/deployment_guide/>`_.
+  For detailed deployment procedures, refer to the :doc:`Deployment Guide </deployment_guide/index>`.
diff --git a/docs/user_guide/faq/workflow.in.rst b/docs/user_guide/faq/workflow.in.rst
@@ -137,6 +137,8 @@ It is equivalent to first shell into the task and then run the command manually:
 
   $ /bin/sh -c "kill -9 $( ps aux | grep '[p]ython' | head -n1 | awk '{print $2}' )"
 
+.. _faq_workflow_resource_usage:
+
 How to determine the resource usage of a workflow?
 --------------------------------------------------
 
diff --git a/docs/user_guide/getting_started/install/index.rst b/docs/user_guide/getting_started/install/index.rst
@@ -56,7 +56,7 @@ Login
 .. important::
 
    The OSMO client can only be used to connect to already deployed OSMO web services. Please contact your administrator
-   and refer to the `Deployment Guides <https://nvidia.github.io/OSMO/deployment_guide/main/introduction/whats_next.html>`_ for more information.
+   and refer to the :doc:`Deployment Guides </deployment_guide/introduction/whats_next>` for more information.
 
 To login to the client, can use the following command:
 
diff --git a/docs/user_guide/getting_started/system_requirements.rst b/docs/user_guide/getting_started/system_requirements.rst
@@ -16,7 +16,7 @@
   SPDX-License-Identifier: Apache-2.0
 ..
 
-.. _system_requirements:
+.. _getting_started_system_requirements:
 
 ===================
 System Requirements
diff --git a/docs/user_guide/tutorials/hello_world/index.rst b/docs/user_guide/tutorials/hello_world/index.rst
@@ -102,7 +102,7 @@ The following steps will guide you through submitting a workflow to OSMO using t
 
 .. seealso::
 
-  Please refer to :ref:`System Requirements <system_requirements>` for the recommended web browsers.
+  Please refer to :ref:`System Requirements <getting_started_system_requirements>` for the recommended web browsers.
 
 .. image:: ui_hello_world.gif
   :alt: OSMO Web UI workflow
diff --git a/docs/user_guide/tutorials/parallel_workflows/index.rst b/docs/user_guide/tutorials/parallel_workflows/index.rst
@@ -79,6 +79,8 @@ Independent tasks run in parallel asynchronously when they:
 All three tasks start simultaneously (resource availability permitting). They cannot
 communicate with each other over the network.
 
+.. _tutorials_parallel_workflows_groups:
+
 **Groups**
 ==========
 
diff --git a/workflows/README.md b/workflows/README.md
@@ -22,7 +22,7 @@ This directory contains brief examples of workflows that can be used in combinat
 
 ## Tutorials
 
-> [Collection of workflows](./tutorials/) from the [tutorial documentation](https://nvidia.github.io/OSMO/user_guide/tutorials/overview.html)
+> [Collection of workflows](./tutorials/) from the [tutorial documentation](https://nvidia.github.io/OSMO/user_guide/main/tutorials/overview.html)
 
 ## How-To Guides
 

Original file line number	Diff line number	Diff line change
`@@ -255,4 +255,4 @@ Troubleshooting`
`255`	`255`
`256`	`256`	`.. seealso::`
`257`	`257`
`258`		- - Learn more about Rsync in OSMO at `Interactive Workflows <https://nvidia.github.io/OSMO/user_guide/workflows/interactive/rsync.html>`_
	`258`	+ - Learn more about Rsync in OSMO at :doc:`Interactive Workflows </user_guide/workflows/interactive/rsync>`