Skip to content

Documentation

This directory (under apps/docs) contains the documentation for the BitonicAI projects, built with MkDocs and mkdocstrings.

Building the Documentation

Prerequisites

Install the documentation dependencies (from the workspace root):

uv sync --package docs

Build

Build the static site:

uv run --project apps/docs mkdocs build

The output will be in apps/docs/site/.

Serve Locally

Serve the documentation locally for development:

uv run --project apps/docs mkdocs serve

The documentation will be available at http://localhost:8000

Documentation Structure

  • index.md - Main documentation homepage
  • at_scorer/ - ATS Scorer package documentation
  • bitonicai/ - BitonicAI service documentation

Adding Documentation

Adding New API Reference Pages

  1. Create a new markdown file in the appropriate directory
  2. Use the module.path syntax to include docstrings:
# Module Name

::: module.path.to.Class
    options:
      show_root_heading: true
      show_source: true
  1. Add the page to mkdocs.yml in the nav section

Writing Guide Pages

Create markdown files with standard Markdown syntax. Use code blocks with language tags for examples.

Updating Documentation

Documentation is automatically generated from docstrings in the source code. To update:

  1. Update docstrings in the source code
  2. Rebuild the documentation: mkdocs build
  3. Preview changes: mkdocs serve

Docker Build

Build and serve documentation using Docker:

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

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

Or use the helper script:

./apps/docs/docs/docker-build.sh
docker run -p 8080:80 bitonicai-docs

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

The Docker build: - Uses a multi-stage build (builder + nginx) - Installs all documentation dependencies - Builds the static site - Serves with nginx in production

Deployment

GitHub Pages

Prerequisites

  1. Ensure your repository is on GitHub
  2. Dependencies are managed with uv (no pip). Run: 
    uv sync --package docs

Automatic Deployment

The easiest way to deploy to GitHub Pages is using the gh-deploy command:

uv run --project apps/docs mkdocs gh-deploy

This command will: 1. Build the documentation 2. Create a gh-pages branch (if it doesn't exist) 3. Commit the built site to the gh-pages branch 4. Push to GitHub

Manual Deployment

If you prefer more control:

# 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

# Return to main branch
git checkout main

Create .github/workflows/docs.yml (already present):

name: Deploy Documentation

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'packages/**'
      - 'apps/**'
  workflow_dispatch:

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install uv
        uses: astral-sh/setup-uv@v4
      - name: Install dependencies
        run: uv sync --frozen --no-dev --package docs
      - name: Build documentation
        working-directory: apps/docs
        run: uv run mkdocs build --strict
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./apps/docs/site

Configure GitHub Pages

  1. Go to your repository Settings
  2. Navigate to Pages
  3. Under "Source", select "Deploy from a branch"
  4. Select gh-pages branch and / (root) folder
  5. Click Save

Your documentation will be available at: https://<username>.github.io/<repository-name>/

Docker Deployment

Build and run the documentation container:

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

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

# Visit http://localhost:8080

Other Platforms

  • Netlify: Build command uv sync --package docs && uv run --project apps/docs mkdocs build, publish apps/docs/site/
  • Read the Docs: Configure via .readthedocs.yml
  • Vercel: Build command uv sync --package docs && uv run --project apps/docs mkdocs build