Documentation Deployment Guide

This guide covers various methods for deploying the BitonicAI documentation.

Docker Deployment

Building Documentation with Docker

The documentation can be built and served using Docker:

# Build the documentation image
docker build -f apps/docs/Dockerfile.docs -t bitonicai-docs .

# Run the container locally
docker run -p 8080:80 bitonicai-docs

Visit http://localhost:8080 to view the documentation.

Docker Build Process

The Dockerfile.docs uses a multi-stage build:

Builder stage: Installs dependencies and builds the static site
Production stage: Uses nginx to serve the built documentation

Customizing the Docker Build

To customize the build:

Modify Dockerfile.docs to add additional dependencies
Add custom nginx configuration if needed
Adjust build arguments as necessary

GitHub Pages Deployment

Prerequisites

GitHub repository with documentation source
Dependencies installed via uv (no pip):
```
uv sync --package docs
```

Method 1: GitHub Actions (Recommended)

The repository includes a GitHub Actions workflow (.github/workflows/docs.yml) that automatically deploys documentation.

Setup:

Enable GitHub Pages:
Go to repository Settings → Pages
Under "Source", select "Deploy from a branch"
Select gh-pages branch and / (root) folder
Click Save

Push changes:

git add .
git commit -m "Update documentation"
git push origin main

The workflow will automatically:
Build the documentation
Deploy to the gh-pages branch
Make it available at https://<username>.github.io/<repository-name>/

Workflow triggers: - Pushes to main branch - Changes to docs/, mkdocs.yml, or source code - Manual trigger via workflow_dispatch

Method 2: Manual Deployment with `mkdocs gh-deploy`

# Deploy to GitHub Pages
uv run --project apps/docs mkdocs gh-deploy

This command: 1. Builds the documentation 2. Creates/updates the gh-pages branch 3. Pushes to GitHub

Method 3: Manual Git Deployment

For more control over the deployment process:

# Build the site
uv run --project apps/docs mkdocs build

# Create or checkout gh-pages branch
git checkout --orphan gh-pages
git rm -rf .

# Copy built site
cp -r site/* .

# Commit and push
git add .
git commit -m "Deploy documentation"
git push origin gh-pages --force

# Return to main branch
git checkout main

Custom Domain

To use a custom domain (e.g., docs.bitonicai.com):

Add a CNAME file to docs/ directory:
```
docs.bitonicai.com
```
Update mkdocs.yml:
```
site_url: https://docs.bitonicai.com
```
Configure DNS:
Add a CNAME record pointing to <username>.github.io
Or add A records for GitHub Pages IPs
In GitHub repository Settings → Pages, add your custom domain

Other Deployment Options

Netlify

Connect your repository to Netlify
Configure build settings:
Build command: uv sync --package docs && uv run --project apps/docs mkdocs build
Publish directory: apps/docs/site
Deploy

Vercel

Create vercel.json:

{
  "buildCommand": "uv sync --package docs && uv run --project apps/docs mkdocs build",
  "outputDirectory": "apps/docs/site"
}

Connect repository and deploy

Read the Docs

Create .readthedocs.yml:

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"
python:
  install:
    - path: apps/docs

Connect repository to Read the Docs
Configure and build

Custom Server

Build the site:

uv run --project apps/docs mkdocs build

Upload the apps/docs/site/ contents to your web server
Configure your web server to serve the static files

Troubleshooting

GitHub Pages Not Updating

Check GitHub Actions workflow status
Verify gh-pages branch exists and has content
Ensure GitHub Pages is enabled in repository settings
Check for build errors in Actions logs

Docker Build Fails

Verify all required files are present (mkdocs.yml, docs/)
Check that source code paths are correct
Ensure Python dependencies install successfully

Documentation Not Rendering

Verify mkdocs.yml syntax is correct
Check that docstring paths in API reference pages are valid
Ensure all dependencies are installed
Run uv run --project apps/docs mkdocs build --strict to catch errors

Best Practices

Test locally before deploying:
```
mkdocs serve
```
Use version control for documentation changes
Automate deployment with GitHub Actions
Monitor build status in GitHub Actions
Keep dependencies updated in apps/docs/pyproject.toml
Document deployment process for team members