GitHub Pages Automatic Deployment

For Developers: Setting up Continuous Documentation Deployment

This guide explains how the documentation is automatically built and deployed to GitHub Pages, and how to troubleshoot deployment issues.

Last Updated: October 23, 2025 Version: 0.8.6 Status: Production-Ready

Overview

The documentation deployment system uses GitHub Actions to automatically:

  1. Build Sphinx documentation on every push

  2. Deploy to GitHub Pages via gh-pages branch

  3. Make documentation live at https://username.github.io/repo-name

This is a hands-off continuous deployment system requiring zero manual intervention after initial setup.

Architecture

Deployment Flow

Developer Push Code
      ↓
GitHub Detects Changes
      ↓
GitHub Actions Triggered (.github/workflows/deploy-docs.yml)
      ↓
[BUILD JOB]
• Setup Python 3.13
• Install dependencies
• Run: cd docs/sphinx && make clean html
• Upload artifact (7-day retention)
      ↓
[DEPLOY JOB]
• Download build artifact
• Configure GitHub Pages
• Upload to gh-pages branch
• Live at: https://username.github.io/repo-name
      ↓
Documentation Available (1-2 minutes)

Build & Deploy Jobs

The workflow has two separate jobs following professional CI/CD patterns:

Build Job (ubuntu-latest)

  • Setup: Python 3.13, system dependencies (make)

  • Install: All packages from requirements.txt

  • Build: Sphinx documentation with caching

  • Output: Artifacts stored 7 days (debugging support)

  • Runs on: Every push, pull requests, manual trigger

Deploy Job (ubuntu-latest)

  • Dependency: Requires build job to succeed

  • Condition: Only runs on main, master branches

  • Action: Uploads to gh-pages branch

  • Result: GitHub Pages auto-deploys from gh-pages

Why Separate Jobs?

  • ✅ Reliability: Retry deploy without rebuilding

  • ✅ Debugging: Keep build artifacts for investigation

  • ✅ Safety: Deploy only on main branches (PR builds safe)

  • ✅ Scalability: Easy to add additional deployment targets

  • ✅ Performance: Can parallelize in future

Configuration Files

.github/workflows/deploy-docs.yml

Main GitHub Actions workflow file.

Triggers:

on:
  push:
    branches:
      - main
      - master
      - develop
    paths:
      - 'docs/**'
      - 'scripts/**'
      - '__version__.py'
      - 'main.py'
      - 'config.py'
      - 'requirements.txt'
      - '.github/workflows/deploy-docs.yml'
  pull_request:
    branches:
      - main
      - master
  workflow_dispatch:  # Manual trigger

Build Job Steps:

- Checkout repository (with full history)
- Set up Python 3.13
- Install system dependencies (make)
- Install Python dependencies (cached pip)
- Build documentation: cd docs/sphinx && make clean html
- Upload build artifact (7-day retention)

Deploy Job Steps:

- Download build artifact
- Setup GitHub Pages
- Upload to GitHub Pages
- Deploy to gh-pages branch
- Success notification

See .github/workflows/deploy-docs.yml for complete configuration.

.nojekyll

Empty file that tells GitHub Pages to serve content as-is without Jekyll processing.

Why needed: Sphinx generates HTML structure that Jekyll would incorrectly process, breaking links and styling. This file disables Jekyll.

Location: Repository root (automatically served by GitHub Pages)

Content: Empty or comment-only

requirements.txt

All Python dependencies including Sphinx packages:

sphinx>=7.0.0                      # Documentation generator
sphinx-rtd-theme>=1.3.0            # Read the Docs theme
sphinx-autodoc-typehints>=1.24.0   # Type hints rendering
sphinx-autobuild>=2021.3.14        # Auto-rebuild on file changes

.gitignore

Already configured to exclude:

docs/sphinx/_build/                # Built HTML (not committed)

Setup Instructions

One-Time Setup

Step 1: Verify Files Exist

# Check workflow file
ls -la .github/workflows/deploy-docs.yml

# Check GitHub Pages config
ls -la .nojekyll

# Check dependencies
grep sphinx requirements.txt

Step 2: Commit Files

git add .github .nojekyll
git commit -m "Add automatic GitHub Pages deployment"
git push origin main

Step 3: Watch Workflow Run

  1. Go to GitHub repository

  2. Click Actions tab

  3. Look for “Build and Deploy Documentation”

  4. Should show: ⏳ In Progress → ✅ Passed

Step 4: Configure GitHub Pages

  1. Go to Settings → Pages (left sidebar)

  2. Under Build and deployment: - Source: Deploy from a branch - Branch: gh-pages (appears after first build) - Folder: /root

  3. Click Save

Step 5: Access Documentation

After ~1-2 minutes:

URL: https://your-username.github.io/repo-name
Example: https://myusername.github.io/RePORTaLiN

Local Testing

Before pushing to GitHub, verify locally:

# Test 1: Build documentation
make clean-docs
make docs

# Test 2: Check output exists
ls -la docs/sphinx/_build/html/index.html

# Test 3: View locally
make docs-open

# Test 4: Live reload development
make docs-watch
# Then visit: http://127.0.0.1:8000

Performance

Build Times

Build Type

Expected Time

First build (fresh install)

2-3 minutes

Subsequent builds (cached)

30-60 seconds

Cache retention

5 days

Why slow first time: Downloads and installs all pip dependencies

Why fast after: Pip dependencies cached in GitHub Actions

Bandwidth & Quota

GitHub Pages:

  • Unlimited bandwidth for public repositories

  • No strict size limits for reasonable sizes

GitHub Actions:

  • Public repos: Unlimited free usage

  • Private repos: 2,000 minutes/month free

  • Current build: ~30-60 seconds per build

  • Monthly estimate: Minimal quota usage

Troubleshooting

Workflow Shows Red (Failed)

Step 1: Check Error Logs

  1. Go to Actions tab

  2. Click the failed workflow run

  3. Click build job

  4. Scroll down to find error message

Step 2: Common Issues

Error

Solution

ModuleNotFoundError: No module named

Add package to requirements.txt Then run: make docs locally

Sphinx build fails (warnings as errors)

Fix .rst syntax errors in docs Run: make docs locally to debug

make: command not found

Workflow installs make automatically Only happens if Ubuntu image changes

Import errors in conf.py

Check sys.path.insert() in conf.py Verify __version__.py exists

Step 3: Debug Locally

# Build exactly like the workflow does
cd docs/sphinx
make clean html

# If that works, problem is environment-specific
# If that fails, you found the issue to fix

Documentation Not Updating

Check 1: Verify Workflow Ran

  1. Go to Actions tab

  2. Find latest “Build and Deploy Documentation” run

  3. Check status (should be ✅ Passed)

Check 2: Clear Browser Cache

macOS: Cmd+Shift+R
Windows/Linux: Ctrl+Shift+R

Check 3: Verify GitHub Pages Settings

  1. Go to Settings → Pages

  2. Verify: - Source: Deploy from a branch - Branch: gh-pages (not main) - Folder: /root

  3. Click Save again

Check 4: Wait for Propagation

GitHub Pages takes 1-3 minutes to propagate. Wait and refresh.

Build Succeeds But Docs Don’t Appear

Issue: Workflow shows ✅ Passed but docs not live

Solution:

  1. Go to Settings → Pages

  2. Verify gh-pages branch is selected

  3. Verify folder is /root

  4. Click Save

  5. Wait 2-3 minutes

  6. Visit URL again

If still not working:

  1. Delete gh-pages branch locally and remote

  2. Run workflow again (or push code)

  3. Workflow recreates gh-pages branch

  4. Reconfigure Settings → Pages

Manual Deployment

Trigger Build Manually

To rebuild docs without pushing code:

  1. Go to GitHub repository

  2. Click Actions tab

  3. Click Build and Deploy Documentation

  4. Click Run workflow button

  5. Select branch (usually main)

  6. Click Run workflow

Wait ~1-2 minutes for build to complete.

Redeploy Old Version

To re-deploy a previous version:

  1. Go to Actions tab

  2. Find successful workflow run (scroll through history)

  3. Click the run

  4. Click Re-run failed jobs or Re-run all jobs

Previous version rebuilds and redeploys.

Disable Auto-Deploy

To temporarily disable automatic deployment:

Option 1: Disable workflow

  1. Go to Actions tab

  2. Click Build and Deploy Documentation

  3. Click ⋯ (three dots)

  4. Select Disable workflow

Option 2: Delete workflow file

git rm .github/workflows/deploy-docs.yml
git commit -m "Disable automatic deployment"
git push

Re-enable: Restore the workflow file or click Enable workflow

Custom Domain (Advanced)

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

Step 1: Create DNS Record

Create CNAME or A record pointing to GitHub Pages:

CNAME: docs.mysite.com → username.github.io

Step 2: Configure GitHub Pages

  1. Go to Settings → Pages

  2. Enter domain in Custom domain field

  3. GitHub creates CNAME file automatically

  4. Enable Enforce HTTPS when available

Step 3: Wait for SSL Certificate

GitHub provisions SSL certificate (takes 24 hours).

Monitoring & Maintenance

View Build Artifacts

Build artifacts are stored 7 days for debugging:

  1. Go to Actions tab

  2. Click workflow run

  3. Scroll to Artifacts section

  4. Download documentation artifact

Useful for debugging failed builds.

Check GitHub Actions Quota

For private repositories (public repos have unlimited):

  1. Go to Settings → Billing and plans

  2. Click Actions (left sidebar)

  3. View usage for current month

Current build time (~30-60 sec) uses minimal quota.

Update Documentation

Documentation updates automatically on every push:

# Edit documentation files
vim docs/sphinx/user_guide/quickstart.rst

# Test locally
make docs

# Commit and push
git add docs/
git commit -m "Update documentation"
git push origin main

# Workflow automatically runs
# Docs update live in 2-5 minutes

Modify Workflow

To modify the GitHub Actions workflow:

  1. Edit .github/workflows/deploy-docs.yml

  2. Make changes

  3. Test locally if possible: make docs

  4. Commit and push

  5. Workflow uses new configuration

Common modifications:

  • Change trigger branches

  • Add path filters

  • Change Python version

  • Add build steps

Best Practices

✅ DO

✅ Commit documentation changes with code changes ✅ Test documentation locally before pushing ✅ Use consistent RST formatting ✅ Update version in __version__.py for major changes ✅ Include examples in documentation ✅ Use descriptive commit messages

❌ DON’T

❌ Don’t commit build artifacts (_build/) ❌ Don’t manually edit gh-pages branch ❌ Don’t bypass documentation review ❌ Don’t leave broken links in documentation ❌ Don’t mix Markdown and RST (use only RST) ❌ Don’t modify workflow without testing locally

Verification Checklist

Before considering setup complete:

Setup Verification

# ✓ Check 1: Files exist
[ -f .github/workflows/deploy-docs.yml ] && echo "✓ Workflow file exists"
[ -f .nojekyll ] && echo "✓ GitHub Pages config exists"

# ✓ Check 2: Dependencies in requirements.txt
grep sphinx requirements.txt && echo "✓ Sphinx configured"

# ✓ Check 3: Documentation builds
make docs && echo "✓ Local build works"

# ✓ Check 4: Files committed
git log --oneline -n 5 | grep -i pages && echo "✓ Files committed"

Deployment Verification

After first push:

✓ Workflow started (visible in Actions tab)
✓ Build succeeded (green checkmark)
✓ gh-pages branch created
✓ Settings → Pages shows gh-pages branch
✓ Documentation accessible at live URL
✓ Search functionality working
✓ Links not broken
✓ Styling displaying correctly

See Also