Building the Docs#

This guide explains how to compile the Clera documentation from source using Sphinx. Follow these steps any time you update .rst files and want to regenerate the HTML output.

Prerequisites#

You need Python 3.7+ and pip installed. Install the required packages once:

pip install sphinx sphinx-book-theme

Verify Sphinx is available:

sphinx-build --version

Project Structure#

The documentation lives in the rtd/ folder:

rtd/
├── Makefile          # Linux / macOS build script
├── make.bat          # Windows build script
├── source/
│   ├── conf.py       # Sphinx configuration
│   ├── index.rst     # Table of contents root
│   ├── _pages/       # All documentation pages (.rst files)
│   ├── _static/      # Static assets (CSS, images, favicon)
│   └── _templates/   # Optional Jinja2 HTML templates
└── build/
    └── html/         # Generated HTML output (after build)

Building the HTML#

Step 1 — Open a terminal and navigate to the rtd/ folder:

cd path/to/your/project/rtd

Step 2 — Run the build command:

On Linux / macOS:

make html

On Windows:

make.bat html

Sphinx will read source/conf.py, process all .rst files, and write the rendered HTML into build/html/.

Step 3 — Open the output in your browser:

# Linux / macOS
open build/html/index.html

# Windows
start build/html/index.html

Cleaning the Build#

If you encounter stale output or want a full rebuild, clean the build/ directory first:

On Linux / macOS:

make clean
make html

On Windows:

make.bat clean
make.bat html

Alternatively, delete the build/ folder manually and re-run the build command.

Updating the Version Number#

The release version displayed in the docs is set in source/conf.py:

release = '0.3.0'

Update this string whenever you cut a new release, then rebuild.

Adding a New Page#

Create a new .rst file inside source/_pages/.
Open source/index.rst and add the file path (without the .rst extension) to the toctree directive:
```
.. toctree::
   :maxdepth: 2
   :hidden:

   _pages/Your New Page
```
Rebuild with make html.

Deploying to Read the Docs#

The repository includes a readthedocs.yaml configuration file at the rtd/ root. When connected to a Read the Docs account:

Push your changes to the linked repository.
Read the Docs will detect the readthedocs.yaml file, install dependencies from source/requirements.txt, and build the docs automatically.
The live docs URL will update within a few minutes.

To trigger a manual rebuild, log in to your Read the Docs dashboard, select the project, and click Build.

Troubleshooting#

sphinx-build: command not found — Run pip install sphinx and ensure your Python Scripts (Windows) or bin (Linux/macOS) directory is on your PATH.
Theme not found error — Run pip install sphinx-book-theme.
Broken references or warnings — Sphinx prints the file and line number. Fix the .rst source file and rebuild.
Stale pages not updating — Run make clean before make html to force a full rebuild.

Building the Docs

Contents