Documentation Website Guide

August 5, 2026 ยท View on GitHub

Guide for setting up, running, and configuring the MkDocs documentation site. For adding or modifying generated content (images, release notes, support policy), see DEVELOPMENT.md.

Prerequisites

# Set up virtual environment from repository root
cd /path/to/deep-learning-containers
uv venv --python 3.12
source .venv/bin/activate
uv pip install -r docs/requirements.txt

Local Development

Generation Only

Run the generation system without serving:

python docs/src/main.py --verbose

This clones the tutorials/ repository and generates markdown files in reference/ and releasenotes/ directories.

Generation flags:

python docs/src/main.py --available-images-only
python docs/src/main.py --support-policy-only
python docs/src/main.py --release-notes-only
python docs/src/main.py --index-only

Serving

Use mkdocs serve to generate documentation and serve the website:

mkdocs serve

The site is typically available at http://127.0.0.1:8000/deep-learning-containers/ - check the command output for the actual URL.

Live Reload

Enable automatic reload on content changes:

mkdocs serve --livereload

Note: Live reload only detects changes to:

  • Markdown file content
  • .nav.yml content
  • mkdocs.yml content

Live reload does not detect changes requiring documentation regeneration (e.g., image config YAML files, templates). To regenerate documentation, stop the server (Ctrl+C) and rerun mkdocs serve.

Running Tests

The documentation tests live under test/docs/.

# From the repository root, with the virtual environment activated
uv pip install -r test/requirements.txt
cd test/
python3 -m pytest -vs -rA docs

Site navigation is managed centrally in docs/.nav.yml using the awesome-nav plugin. Structure:

nav:
  - Home: index.md
  - Section Name:
      - section/index.md
      - Page Title: section/page.md
  - Directory Reference: dirname  # Auto-discovers pages in directory

Configuration

Key settings in mkdocs.yaml:

Theme Palette - Modify color scheme under theme.palette:

theme:
  palette:
    - scheme: default    # light mode
      primary: custom
      accent: custom

Plugins - Add/remove plugins under plugins:

plugins:
  - search
  - autorefs
  - awesome-nav