117 lines
3.4 KiB
Markdown
117 lines
3.4 KiB
Markdown
---
|
|
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
title: 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)
|
|
|
|
## Redirect Creation
|
|
|
|
When moving or renaming files a redirect must be created.
|
|
|
|
Redirect entries should be added to the `redirects` dictionary in `conf.py`. For detailed information on redirect syntax, see the [sphinx-reredirects usage documentation](https://documatt.com/sphinx-reredirects/usage/#introduction).
|
|
|
|
## 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
|
|
```
|