docs/README.md

Building Documentation

We use Sphinx with the Book Theme for maintaining and generating our documentation.

Note: To avoid dependency conflicts, we strongly recommend using a Python virtual environment to isolate the required dependencies from your system's global Python environment.

Current-Version Documentation

This section describes how to build the documentation for the current version of the project.

Linux

# 1. Navigate to the docs directory and install dependencies
cd docs
pip install -r requirements.txt

# 2. Build the current documentation
make current-docs

# 3. Open the current docs
xdg-open _build/current/index.html

# 3. Option B: Serve locally (handy over SSH)
make serve-current  # serves http://127.0.0.1:8000

Windows

:: 1. Navigate to the docs directory and install dependencies
cd docs
pip install -r requirements.txt

:: 2. Build the current documentation
make current-docs

:: 3. Open the current docs
start _build\current\index.html

Multi-Version Documentation

This section describes how to build the multi-version documentation, which includes previous tags and the main branch.

Linux

# 1. Navigate to the docs directory and install dependencies
cd docs
pip install -r requirements.txt

# 2. Build the multi-version documentation
make multi-docs

# 3. Open the multi-version docs
xdg-open _build/index.html

Windows

:: 1. Navigate to the docs directory and install dependencies
cd docs
pip install -r requirements.txt

:: 2. Build the multi-version documentation
make multi-docs

:: 3. Open the multi-version docs
start _build\index.html