DPG Documentation#

This directory contains the Sphinx-based documentation for DPG.

Build and Serve Locally#

Prerequisites#

Install the documentation dependencies:

pip install ".[docs]"

This installs:

  • sphinx - Documentation generator

  • pydata-sphinx-theme - Theme (same as NumPy, pandas, scikit-learn)

  • sphinx-autoapi - Auto-generate API docs from docstrings

  • myst-parser - Markdown support

  • sphinx-copybutton - Copy button for code blocks

  • sphinx-design - Grid cards, tabs, badges

Build the Documentation#

sphinx-build -b html docs/ docs/_build/html

Serve Locally#

Option 1: Python HTTP Server (Recommended)

cd docs/_build/html
python3 -m http.server 8000

Then open http://localhost:8000 in your browser.

VS Code Remote SSH: VS Code will automatically forward port 8000 and provide a clickable link in the terminal output or the Ports panel.

Option 2: Open directly in browser

# Linux
xdg-open docs/_build/html/index.html

# macOS
open docs/_build/html/index.html

# Windows
start docs/_build/html/index.html

Option 3: Sphinx Autobuild (Auto-reload on changes)

pip install sphinx-autobuild
sphinx-autobuild docs/ docs/_build/html --open-browser

Documentation Structure#

  • index.md - Main landing page

  • quickstart.md - Quick start guide

  • conf.py - Sphinx configuration

  • _static/ - Custom CSS, JS, images

  • _build/ - Generated HTML (git-ignored)

API Reference#

The API documentation is auto-generated from docstrings using sphinx-autoapi. It scans:

  • dpg/ - Main DPG package

  • metrics/ - Metrics package

No need to manually write API docs - just add proper docstrings to your Python code!

Publishing#

Documentation is automatically built and deployed to ReadTheDocs via the CI/CD pipeline (see .github/workflows/docs.yml) when changes are merged to the main branch.

Troubleshooting#

Warning: “Unknown type: placeholder” This is a known benign warning from sphinx-autoapi when it encounters C-extension types. It’s filtered out in the CI build but you may see it locally. Safe to ignore.

Module not found errors Make sure you’ve installed the package:

pip install -e .

Graphviz not found (for diagrams) The documentation doesn’t require Graphviz unless you’re embedding diagrams. If needed:

  • Ubuntu/Debian: sudo apt-get install graphviz

  • macOS: brew install graphviz

  • Windows: winget install Graphviz.Graphviz

Note: Graphviz is NOT required for basic doc builds.