docs: move doc build dependencies to pyproject.toml (#3453)

Signed-off-by: Neal Vaidya <nealv@nvidia.com>

.dockerignore

@@ -39,4 +39,6 @@
 .dockerignore
 **/target/*
 **/*safetensors
-container/Dockerfile*
+container/Dockerfile*
+.venv
+.venv-docs

.gitignore

@@ -68,6 +68,7 @@ llm_engine.h
 
 ### Virtual Environment ###
 .venv/
+.venv-docs/
 
 ### Ruff ###
 .ruff_cache/

container/Dockerfile.docs

@@ -21,22 +21,27 @@ RUN apt-get update && \
     apt-get install -y --no-install-recommends \
         build-essential=12.10ubuntu1 \
         curl=8.5.0-2ubuntu10.6 \
-        doxygen=1.9.8+ds-2build5 \
-        pandoc=3.1.3+ds-2 \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /workspace/dynamo
 
-ENV VIRTUAL_ENV=/workspace/dynamo/.venv
-RUN uv venv $VIRTUAL_ENV --python 3.12
+# Copy pyproject.toml first for better layer caching
+COPY pyproject.toml .
 
-RUN --mount=type=bind,source=./container/deps/requirements.docs.txt,target=requirements.txt \
-    uv pip install --requirement requirements.txt
+# Create venv and install docs dependencies from dependency group
+# Note: We use `uv pip install --group` instead of `uv run --only-group` because
+# uv run always tries to resolve project dependencies (including ai-dynamo-runtime),
+# even with --only-group flag. Using a dedicated venv lets us build the docs without
+# needing to build the runtime first.
+ENV VIRTUAL_ENV=/workspace/dynamo/.venv-docs
+RUN uv venv $VIRTUAL_ENV --python 3.12 && \
+    uv pip install --python $VIRTUAL_ENV --group docs
 
 # Set visitor script to be included on every HTML page
 ENV VISITS_COUNTING_SCRIPT="//assets.adobedtm.com/b92787824f2e0e9b68dc2e993f9bd995339fe417/satelliteLib-7ba51e58dc61bcb0e9311aadd02a0108ab24cc6c.js"
 
+# Copy the rest of the code
 COPY . /workspace/dynamo
 
-RUN . .venv/bin/activate && \
-    python3 docs/generate_docs.py
+# Run docs generation using uv run with the docs venv
+RUN uv run --python .venv-docs --no-project docs/generate_docs.py

container/deps/requirements.docs.txt

@@ -1,108 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-ablog==0.11.12
-accessible-pygments==0.0.5
-alabaster==1.0.0
-asttokens==3.0.0
-attrs==25.3.0
-babel==2.17.0
-beautifulsoup4==4.13.4
-bleach==6.2.0
-breathe==4.36.0
-certifi==2025.6.15
-charset-normalizer==3.4.2
-click==8.2.1
-comm==0.2.2
-debugpy==1.8.14
-decorator==5.2.1
-defusedxml==0.7.1
-docutils==0.21.2
-executing==2.2.0
-exhale==0.3.7
-fastjsonschema==2.21.1
-feedgen==1.0.0
-greenlet==3.2.3
-httplib2==0.22.0
-idna==3.10
-imagesize==1.4.1
-importlib-metadata==8.7.0
-invoke==2.2.0
-ipykernel==6.29.5
-ipython==9.3.0
-ipython-pygments-lexers==1.1.1
-jedi==0.19.2
-jinja2==3.1.6
-jsonschema==4.24.0
-jsonschema-specifications==2025.4.1
-jupyter-cache==1.0.1
-jupyter-client==8.6.3
-jupyter-core==5.8.1
-jupyterlab-pygments==0.3.0
-latexcodec==3.0.1
-lxml==5.4.0
-markdown-it-py==3.0.0
-markupsafe==3.0.2
-matplotlib-inline==0.1.7
-mdit-py-plugins==0.4.2
-mdurl==0.1.2
-mistune==3.1.3
-myst-nb==1.2.0
-myst-parser==4.0.1
-nbclient==0.10.2
-nbconvert==7.16.6
-nbformat==5.10.4
-nbsphinx==0.9.7
-nest-asyncio==1.6.0
-nvidia-sphinx-theme==0.0.8
-packaging==25.0
-pandocfilters==1.5.1
-parso==0.8.4
-pexpect==4.9.0
-platformdirs==4.3.8
-prompt-toolkit==3.0.51
-psutil==7.0.0
-ptyprocess==0.7.0
-pure-eval==0.2.3
-pybtex==0.25.0
-pybtex-docutils==1.0.3
-pydata-sphinx-theme==0.15.4
-pygments==2.19.2
-pyparsing==3.2.3
-python-dateutil==2.9.0.post0
-pyyaml==6.0.2
-pyzmq==27.0.0
-referencing==0.36.2
-requests==2.32.4
-rpds-py==0.25.1
-setuptools==80.9.0
-six==1.17.0
-snowballstemmer==3.0.1
-soupsieve==2.7
-sphinx==8.1.3
-sphinx-book-theme==1.1.4
-sphinx-copybutton==0.5.2
-sphinx-design==0.6.1
-sphinx-prompt==1.9.0
-sphinx-sitemap==2.6.0
-sphinx-tabs==3.4.7
-sphinxcontrib-applehelp==2.0.0
-sphinxcontrib-bibtex==2.6.4
-sphinxcontrib-devhelp==2.0.0
-sphinxcontrib-htmlhelp==2.1.0
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-mermaid==1.0.0
-sphinxcontrib-qthelp==2.0.0
-sphinxcontrib-serializinghtml==2.0.0
-sqlalchemy==2.0.41
-stack-data==0.6.3
-tabulate==0.9.0
-tinycss2==1.4.0
-tornado==6.5.1
-traitlets==5.14.3
-typing-extensions==4.14.0
-urllib3==2.5.0
-watchdog==6.0.0
-wcwidth==0.2.13
-webencodings==0.5.1
-zipp==3.23.0

docs/README.md

@@ -0,0 +1,110 @@
+---
+orphan: true
+---
+
+# Building Documentation
+
+This directory contains the documentation source files for NVIDIA Dynamo.
+
+## Prerequisites
+
+- Python 3.11 or later
+- [uv](https://docs.astral.sh/uv/) package manager
+
+## Build Instructions
+
+### Option 1: Dedicated Docs Environment (Recommended)
+
+This approach builds the docs without requiring the full project dependencies (including `ai-dynamo-runtime`):
+
+```bash
+# One-time setup: Create docs environment and install dependencies
+uv venv .venv-docs
+uv pip install --python .venv-docs --group docs
+
+# Generate documentation
+uv run --python .venv-docs --no-project docs/generate_docs.py
+```
+
+The generated HTML will be available in `docs/build/html/`.
+
+### Option 2: Using Full Development Environment
+
+If you already have the full project dependencies installed (i.e., you're actively developing the codebase), you can use `uv run` directly:
+
+```bash
+uv run --group docs docs/generate_docs.py
+```
+
+This will use your existing project environment and add the docs dependencies.
+
+### Option 3: Using Docker
+
+Build the docs in a Docker container with all dependencies isolated:
+
+```bash
+docker build -f container/Dockerfile.docs -t dynamo-docs .
+```
+
+The documentation will be built inside the container. To extract the built docs:
+
+```bash
+# Run the container and copy the output
+docker run --rm -v $(pwd)/docs/build:/workspace/dynamo/docs/build dynamo-docs
+
+# Or create a container to copy files from
+docker create --name temp-docs dynamo-docs
+docker cp temp-docs:/workspace/dynamo/docs/build ./docs/build
+docker rm temp-docs
+```
+
+This approach is ideal for CI/CD pipelines or when you want complete isolation from your local environment.
+
+## Directory Structure
+
+- `docs/` - Documentation source files (Markdown and reStructuredText)
+- `docs/conf.py` - Sphinx configuration
+- `docs/_static/` - Static assets (CSS, JS, images)
+- `docs/_extensions/` - Custom Sphinx extensions
+- `docs/build/` - Generated documentation output (not tracked in git)
+
+## Dependency Management
+
+Documentation dependencies are defined in `pyproject.toml` under the `[dependency-groups]` section:
+
+```toml
+[dependency-groups]
+docs = [
+    "sphinx>=8.1",
+    "nvidia-sphinx-theme>=0.0.8",
+    # ... other doc dependencies
+]
+```
+
+## Troubleshooting
+
+### Build Warnings
+
+The build process treats warnings as errors. Common issues:
+
+- **Missing toctree entries**: Documents must be referenced in a table of contents
+- **Non-consecutive headers**: Don't skip header levels (e.g., H1 → H3)
+- **Broken links**: Ensure all internal and external links are valid
+
+### Missing Dependencies
+
+If you encounter import errors, ensure the docs dependencies are installed:
+
+```bash
+uv pip install --python .venv-docs --group docs
+```
+
+## Viewing the Documentation
+
+After building, open `docs/build/html/index.html` in your, or use Python's built-in HTTP server:
+
+```bash
+cd docs/build/html
+python -m http.server 8000
+# Then visit http://localhost:8000 in your browser
+```

pyproject.toml

@@ -68,6 +68,27 @@ llama_cpp = [
     "llama-cpp-python",
 ]
 
+[dependency-groups]
+docs = [
+    # Core Sphinx
+    "sphinx>=8.1",
+    "nvidia-sphinx-theme>=0.0.8",
+    # Sphinx extensions
+    "ablog>=0.11",
+    "sphinx-copybutton>=0.5",
+    "sphinx-design>=0.6",
+    "sphinx-prompt>=1.9",
+    "sphinx-sitemap>=2.6",
+    "sphinx-tabs>=3.4",
+    "sphinx-book-theme>=1.1",
+    "sphinxcontrib-mermaid>=1.0",
+    "sphinxcontrib-bibtex>=2.6",
+    # Markdown and notebook support
+    "myst-parser>=4.0",
+    "myst-nb>=1.2",
+    "nbsphinx>=0.9",
+]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"