docs: build multiversion CLI pages from each version's own source (OSMO-6482) (#1156)

* docs: build multiversion CLI pages from each version's own source (OSMO-6482)

The multiversion docs build rendered every version's CLI autodoc/argparse
pages against main's live parser. Older release branches that still ship
commands removed on main (e.g. release/6.3's `osmo bucket`/`osmo dataset`)
therefore failed with `NavigationException`, blocking the build.

Render each version from its own checked-out `src` instead, so each release's
CLI pages reflect the parser it shipped, with no per-release freezing:

- docs/conf.py: resolve the version being built from sphinx-multiversion's
  `-D smv_metadata_path` / `-D smv_current_version` (set for both the html and
  markdown passes) and prepend that version's tree to sys.path. If a legacy
  branch's source cannot be imported in this venv, fall back to the working-tree
  src so the build still succeeds.
- docs/_extensions/module_aliasing.py: skip an `osmo.*` alias when its module
  cannot be imported, instead of aborting the whole build.
- .github/workflows/docs-deploy.yaml: install release/6.3's src requirements so
  its parser imports during the build.

* docs: render per-version CLI via sphinx-multiversion 0.2.7 SOURCEDIR

Adopt the simpler review suggestion now that the sphinx-multiversion fork
0.2.7 passes the environment (including SPHINX_MULTIVERSION_SOURCEDIR) to the
markdown pass as well. conf.py can then resolve each version's checked-out
`src` from that env var alone, instead of parsing the build metadata.

- docs/conf.py: prefer the per-version checkout (SPHINX_MULTIVERSION_SOURCEDIR,
  falling back to cwd) for `src.*` imports.
- docs/Makefile: add --run-markdown-build to build-multiversion (markdown is
  opt-in in 0.2.7).
- docs/locked_requirements.txt: bump the sphinx-multiversion fork to v0.2.7.

* docs: trim verbose comments (review nits)

---------

Co-authored-by: samuelhanono-Nvidia <shanononahmad@nvidia.com>

Author: SamuelHanono

.github/workflows/docs-deploy.yaml

@@ -55,6 +55,10 @@ jobs:
           git fetch
           pip install -U -r docs/locked_requirements.txt
           pip install -U -r src/locked_requirements.txt
+          # Install release/6.3's src requirements so its CLI parser imports
+          # when the multiversion build renders 6.3 from its own checkout.
+          git show origin/release/6.3:src/locked_requirements.txt > /tmp/req-release-6.3.txt
+          pip install -U -r /tmp/req-release-6.3.txt
 
       - name: Build Sphinx documentation
         run: |

docs/Makefile

@@ -47,7 +47,7 @@ build:
 	rm -rf $(OUT_DIR)/_sources
 
 build-multiversion:
-	export OSMO_DOMAIN=public && $(SPHINXBUILD) . $(OUT_DIR)
+	export OSMO_DOMAIN=public && $(SPHINXBUILD) . $(OUT_DIR) --run-markdown-build
 	rm -rf $(OUT_DIR)/_sources
 	@cp _redirect/redirect_user_guide.html $(OUT_DIR)/index.html
 

docs/_extensions/module_aliasing.py

@@ -86,7 +86,9 @@ def _import_and_alias(modname: str):
         osmo_name = _get_osmo_name(src_name)
         sys.modules[osmo_name] = module
         return module
-    except ImportError:
+    except Exception:
+        # Skip aliasing if the module can't import (e.g. a legacy version's
+        # source under newer deps) rather than aborting the whole build.
         return None
 
 

docs/conf.py

@@ -16,6 +16,7 @@
 
 # -- Path setup --------------------------------------------------------------
 
+import os
 import sys
 from pathlib import Path
 
@@ -24,6 +25,12 @@
 # This is important for sphinx-multiversion which runs from temporary directories
 sys.path.insert(0, str(Path(__file__).parent.resolve()))
 
+
+# Import `src.*` from the version being built (its own checkout under
+# sphinx-multiversion) so CLI docs match that release.
+source_dir = Path(os.environ.get("SPHINX_MULTIVERSION_SOURCEDIR", Path.cwd())).resolve()
+sys.path.insert(1, str(source_dir.parent))
+
 # -- Project information -----------------------------------------------------
 
 project = 'NVIDIA OSMO'

docs/locked_requirements.txt

@@ -876,8 +876,8 @@ sphinx-markdown-builder==0.6.8 \
     # via
     #   -r docs_requirements.txt
     #   sphinx-multiversion
-sphinx-multiversion @ https://github.com/RyaliNvidia/sphinx-multiversion/archive/refs/tags/v0.2.5.zip \
-    --hash=sha256:2616bde204930ed6995d9acd86f35770c1d8b02b37383e0653a706b1306f2406
+sphinx-multiversion @ https://github.com/RyaliNvidia/sphinx-multiversion/archive/refs/tags/v0.2.7.zip \
+    --hash=sha256:f8d597ad5e2cd012f08808fe58d712701eacc2eae96e233b73d52956edf48c38
     # via -r docs_requirements.txt
 sphinx-new-tab-link==0.8.0 \
     --hash=sha256:6c757d99f559224a04142c3971c8baa6ac90aca905f15b129d57eeca0ece9582 \