From ff7d43d0870b088f887aef6e51df75ab98974d54 Mon Sep 17 00:00:00 2001 From: Neal Vaidya Date: Tue, 7 Oct 2025 11:55:49 -0700 Subject: [PATCH] docs: move doc build dependencies to pyproject.toml (#3453) Signed-off-by: Neal Vaidya --- .dockerignore | 4 +- .gitignore | 1 + container/Dockerfile.docs | 21 +++-- container/deps/requirements.docs.txt | 108 -------------------------- docs/README.md | 110 +++++++++++++++++++++++++++ pyproject.toml | 21 +++++ 6 files changed, 148 insertions(+), 117 deletions(-) delete mode 100644 container/deps/requirements.docs.txt create mode 100644 docs/README.md diff --git a/.dockerignore b/.dockerignore index ed53513c0..281b3349e 100644 --- a/.dockerignore +++ b/.dockerignore @@ -39,4 +39,6 @@ .dockerignore **/target/* **/*safetensors -container/Dockerfile* \ No newline at end of file +container/Dockerfile* +.venv +.venv-docs \ No newline at end of file diff --git a/.gitignore b/.gitignore index 7661239d1..9bc35b9a2 100644 --- a/.gitignore +++ b/.gitignore @@ -68,6 +68,7 @@ llm_engine.h ### Virtual Environment ### .venv/ +.venv-docs/ ### Ruff ### .ruff_cache/ diff --git a/container/Dockerfile.docs b/container/Dockerfile.docs index 8ccad2d34..70fb4d724 100644 --- a/container/Dockerfile.docs +++ b/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 \ No newline at end of file +# Run docs generation using uv run with the docs venv +RUN uv run --python .venv-docs --no-project docs/generate_docs.py \ No newline at end of file diff --git a/container/deps/requirements.docs.txt b/container/deps/requirements.docs.txt deleted file mode 100644 index c675b9c6e..000000000 --- a/container/deps/requirements.docs.txt +++ /dev/null @@ -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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..9d1f30bbb --- /dev/null +++ b/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 +``` diff --git a/pyproject.toml b/pyproject.toml index a451d93ce..7a6284d68 100644 --- a/pyproject.toml +++ b/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"