Merge pull request #769 from NVIDIA/am/doc-rst

Provide CMS-friendly documentation build

Author: amaslenn

.github/workflows/docs.yml

@@ -3,6 +3,7 @@ name: Build and Deploy Documentation
 on:
   push:
     branches: [ main ]
+    tags: [ 'v*' ]
   workflow_dispatch:    # Allow manual triggering
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
@@ -23,30 +24,44 @@ jobs:
       with:
         enable-cache: true
 
-    - name: Set up environment
-      run: |
-        set -eE
-        set -o pipefail
-
-        uv sync --extra docs
-
     - name: Build documentation
-      run: |
-        set -eE
-        set -o pipefail
-
-        source .venv/bin/activate
-        cd doc
-        make html
-
-    - name: Add .nojekyll file
-      run: touch doc/_build/html/.nojekyll
+      run: make -C doc/ html
 
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v3
       with:
         path: ./doc/_build/html
 
+  build-cms:
+    name: Build CMS Documentation
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v6
+      with:
+        node-version: '24'
+
+    - name: Build CMS documentation
+      run: make -C doc/ cms-html
+
+    - name: Sanitize artifact name
+      id: artifact-name
+      run: echo "name=cloudai-docs-cms-$(echo '${{ github.ref_name }}' | tr '/' '-')" >> $GITHUB_OUTPUT
+
+    - name: Upload CMS docs artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ steps.artifact-name.outputs.name }}
+        path: doc/_build-cms/html
+
   deploy:
     name: Deploy to GitHub Pages
     needs: build

doc/DEV.md

@@ -0,0 +1,91 @@
+Development
+===========
+
+This document targets developers who want to contribute to the project's core.
+
+.. mermaid::
+
+   graph TD
+       subgraph _core
+           base_modules
+           core_implementations
+           registry
+       end
+
+       subgraph runners
+           SlurmRunner
+           StandaloneRunner
+       end
+
+       subgraph installers
+           SlurmInstaller
+           StandaloneInstaller
+       end
+
+       subgraph systems
+           SlurmSystem
+           StandaloneSystem
+       end
+
+       installers --> _core
+       runners --> _core
+       systems --> _core
+
+Core Modules
+------------
+
+We use `import-linter <https://github.com/seddonym/import-linter>`_ to ensure no core modules import higher level modules.
+
+``Registry`` object is a singleton that holds implementation mappings. Users can register their own implementations to the registry or replace the default implementations.
+
+Cache
+-----
+
+Some prerequisites can be installed. For example: Docker images, git repos with executable scripts, etc. All such "installables" are kept under system ``install_path``.
+
+Installables are shared among all tests. So if any number of tests use the same installable, it is installed only once for a particular system TOML.
+
+.. mermaid::
+
+   classDiagram
+       class Installable {
+           <<abstract>>
+           + __eq__(other: object)
+           + __hash__()
+       }
+
+       class DockerImage {
+           + url: str
+           + install_path: str | Path
+       }
+
+       class GitRepo {
+           + git_url: str
+           + commit_hash: str
+           + install_path: Path
+       }
+
+       class PythonExecutable {
+           + git_repo: GitRepo
+           + venv_path: Path
+       }
+
+       Installable <|-- DockerImage
+       Installable <|-- GitRepo
+       Installable <|-- PythonExecutable
+       PythonExecutable --> GitRepo
+
+       class BaseInstaller {
+           <<abstract>>
+           + install(items: Iterable[Installable])
+           + uninstall(items: Iterable[Installable])
+           + is_installed(items: Iterable[Installable]) -> bool
+
+           * install_one(item: Installable)
+           * uninstall_one(item: Installable)
+           * is_installed_one(item: Installable) -> bool
+       }
+
+       BaseInstaller <|-- SlurmInstaller
+       BaseInstaller <|-- StandaloneInstaller
+

doc/DEV.rst

@@ -15,14 +15,45 @@
 # limitations under the License.
 
 SPHINXOPTS    ?=
-SPHINXBUILD  ?= sphinx-build
-SOURCEDIR    = .
-BUILDDIR     = _build
+SOURCEDIR     = .
+BUILDDIR      = _build
+BUILDDIR_CMS  = _build-cms
+
+NODE_MODULES  = $(BUILDDIR_CMS)/node_modules
+MMDC          = $(NODE_MODULES)/.bin/mmdc
+PUPPETEER_CFG = $(BUILDDIR_CMS)/puppeteer-config.json
+
+.PHONY: help html cms-html install-mermaid clean
 
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Available targets:"
+	@echo "  html       - Build documentation for GitHub Pages (nvidia_sphinx_theme) -> $(BUILDDIR)/"
+	@echo "  cms-html   - Build documentation for BrightSpot CMS (sphinx_rtd_theme, PNG mermaid) -> $(BUILDDIR_CMS)/"
+	@echo "  clean      - Remove all build directories"
+
+# Default html target (GitHub Pages)
+html:
+	@echo "Setting up environment for GitHub Pages build..."
+	@cd .. && uv sync --extra docs
+	@echo "Building documentation..."
+	@cd .. && uv run sphinx-build -M html "doc" "doc/$(BUILDDIR)" $(SPHINXOPTS)
+	@touch $(BUILDDIR)/html/.nojekyll
+
+cms-html: install-mermaid
+	@echo "Setting up environment for CMS build..."
+	@cd .. && uv sync --extra docs-cms
+	@echo "Building documentation..."
+	@cd .. && CLOUDAI_DOC_TARGET=cms uv run sphinx-build -M html "doc" "doc/$(BUILDDIR_CMS)" $(SPHINXOPTS)
+
+install-mermaid: $(MMDC)
 
-.PHONY: help Makefile
+$(MMDC):
+	@command -v npm >/dev/null 2>&1 || { echo "Error: npm is required for CMS build but not found. Please install Node.js/npm first."; exit 1; }
+	@echo "Installing @mermaid-js/mermaid-cli via npm..."
+	@mkdir -p $(BUILDDIR_CMS)
+	@cd $(BUILDDIR_CMS) && npm install @mermaid-js/mermaid-cli@^11
+	@echo '{"args": ["--no-sandbox"]}' > $(PUPPETEER_CFG)
+	@echo "mermaid-cli installed successfully."
 
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+clean:
+	@rm -rf $(BUILDDIR) $(BUILDDIR_CMS)