pharos

Blacksmith Documentation

This directory contains the Sphinx documentation for the Blacksmith project.

Building Documentation Locally

Prerequisites

Install the required Python packages:

pip install -r requirements-docs.txt

Build Single Version

To build the documentation for the current branch:

cd docs
make html

The built documentation will be available in docs/_build/html/.

Build Multi-Version

To build documentation for all versions (branches and tags):

cd docs
make multiversion

This will build documentation for:

• The main branch
• All tags matching the pattern v*.*.* (e.g., v1.0.0, v2.1.3)

The built documentation will be available in docs/_build/html/, with each version in its own subdirectory.

Clean Build Artifacts

To remove all build artifacts:

cd docs
make clean

CI/CD Integration

Documentation is automatically built and deployed to GitHub Pages on:

• Pushes to the main branch
• Creation of new version tags (e.g., v1.0.0)

The workflow is defined in .github/workflows/docs-build-deploy.yaml.

Documentation Structure

• conf.py - Sphinx configuration file
• index.rst - Main documentation entry point
• architecture/ - Architecture documentation
• api-endpoints/ - API endpoint documentation
• examples/ - Examples and cookbooks
• operations/ - Operations and infrastructure documentation
• prompt-engineering/ - Prompt engineering documentation
• contributing.rst - Contribution guidelines

Multi-Version Configuration

The multi-version support is configured in conf.py:

• smv_branch_whitelist - Pattern for branches to include (currently main only)
• smv_tag_whitelist - Pattern for tags to include (currently v*.*.*)
• smv_remote_whitelist - Pattern for remotes to use (currently origin only)

Publishing

Documentation is published to GitHub Pages at: https://deerfieldgreen.github.io/blacksmith/

Each version is accessible via:

• Latest: https://deerfieldgreen.github.io/blacksmith/main/
• Version tags: https://deerfieldgreen.github.io/blacksmith/v1.0.0/