name: Documentation Build and Deploy
on:
push:
branches: [ main ]
tags: [ 'v*' ]
pull_request:
branches: [ main ]
paths:
- 'docs/**'
- 'python/**'
- 'mkdocs.yml'
- '.pydocstylerc'
workflow_dispatch:
jobs:
build-docs:
runs-on: ubuntu-latest
permissions:
contents: read
pages: write
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.10'
cache: 'pip'
- name: Cache pip dependencies
uses: actions/cache@v4
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-docs-${{ hashFiles('docs/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-docs-
- name: Install documentation dependencies
run: |
python -m pip install --upgrade pip
pip install -r docs/requirements.txt
- name: Validate docstring quality
run: |
echo "Checking Python docstring quality..."
# Check main Python files
python -m pydocstyle python/rustkmer/ --config=.pydocstylerc || echo "Docstring issues found"
# Count violations (non-blocking for now)
echo "Docstring validation completed"
- name: Build documentation
run: |
echo "Building documentation..."
cd docs
mkdocs build --strict
# Check if docs were built successfully
if [ ! -d "../site" ]; then
echo "Documentation build failed - no site directory created"
exit 1
fi
echo "Documentation built successfully"
- name: Check for broken links
run: |
echo "Checking for broken links..."
cd docs
python ../scripts/check_broken_links.py
- name: Generate documentation stats
run: |
cd docs
echo "Documentation Statistics:"
echo "======================="
# Count pages
page_count=$(find ../site -name "*.html" | wc -l)
echo "HTML pages: $page_count"
# Check size
if [ -d "../site" ]; then
du -sh ../site
fi
# Show API coverage
echo "API Coverage:"
python ../scripts/check_doc_coverage.py
- name: Deploy to GitHub Pages
if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
cd docs
# Configure git user
git config --global user.name "github-actions[bot]"
git config --global user.email "github-actions[bot]@users.noreply.github.com"
# Deploy to GitHub Pages
mkdocs gh-deploy --force --clean
- name: Upload documentation artifact
if: always()
uses: actions/upload-artifact@v4
with:
name: documentation-site
path: site/
retention-days: 30
test-docs:
runs-on: ubuntu-latest
needs: build-docs
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Download documentation artifact
uses: actions/download-artifact@v4
with:
name: documentation-site
path: site/
- name: Test documentation links
run: |
echo "Testing documentation accessibility..."
# Basic check that key pages exist
if [ -f "site/index.html" ]; then
echo "✓ Home page exists"
else
echo "✗ Home page missing"
exit 1
fi
# Check for key API documentation
api_pages=("database" "fuzzyquery" "exceptions" "query" "stats")
for page in "${api_pages[@]}"; do
if [ -f "site/api-reference/${page}.html" ] || [ -f "site/api-reference/${page}/index.html" ]; then
echo "✓ ${page} API docs exist"
else
echo "✗ ${page} API docs missing"
fi
done
- name: Validate MkDocs configuration
run: |
echo "Validating MkDocs configuration..."
cd docs
mkdocs --version
mkdocs build --clean --quiet
# Test that docs build without errors
if mkdocs build --quiet --strict; then
echo "✓ MkDocs configuration is valid"
else
echo "✗ MkDocs configuration has errors"
exit 1
fi
- name: Check Python examples in documentation
run: |
echo "Testing Python examples from documentation..."
# Find Python code blocks in documentation
find site -name "*.html" -exec grep -l "python.*{}" {} \; | while read file; do
echo "Testing examples in: $file"
done || echo "No Python examples found to test"