name: Documentation
on:
push:
branches: [ main ]
paths:
- 'docs/**'
- 'src/**/*.ts'
- 'scripts/generate-docs.js'
- 'README.md'
pull_request:
branches: [ main ]
paths:
- 'docs/**'
- 'src/**/*.ts'
- 'scripts/generate-docs.js'
- 'README.md'
permissions:
contents: write
pages: write
id-token: write
jobs:
# Job 1: Generate and validate documentation
generate-docs:
name: Generate Documentation
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build project
run: npm run build
- name: Generate documentation
run: npm run docs:generate
- name: Validate examples
run: npm run validate:examples
- name: Test documentation links
run: npm run docs:test-links
continue-on-error: true
- name: Upload documentation artifacts
uses: actions/upload-artifact@v4
with:
name: generated-docs
path: docs/generated/
retention-days: 30
- name: Commit updated documentation
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add docs/generated/ || true
if git diff --staged --quiet; then
echo "No documentation changes to commit"
else
git commit -m "docs: update generated documentation [skip ci]"
git push
fi
# Job 2: Deploy to GitHub Pages (only on main branch)
deploy-pages:
name: Deploy to GitHub Pages
runs-on: ubuntu-latest
needs: generate-docs
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
permissions:
pages: write
id-token: write
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build project
run: npm run build
- name: Generate documentation
run: npm run docs:generate
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Setup Ruby for Jekyll
uses: ruby/setup-ruby@v1
with:
ruby-version: '3.1'
bundler-cache: true
working-directory: docs
- name: Create Gemfile for Jekyll
run: |
cd docs
if [ ! -f Gemfile ]; then
cat > Gemfile << 'EOF'
source "https://rubygems.org"
gem "jekyll", "~> 4.3.0"
gem "minima", "~> 2.5"
gem "jekyll-feed", "~> 0.12"
gem "jekyll-sitemap"
gem "jekyll-seo-tag"
gem "jekyll-optional-front-matter"
gem "jekyll-readme-index"
gem "jekyll-default-layout"
gem "jekyll-titles-from-headings"
gem "jekyll-spaceship"
EOF
fi
- name: Install Jekyll dependencies
run: |
cd docs
bundle install
- name: Build Jekyll site
run: |
cd docs
# Ensure index.md has proper Jekyll front matter
if [ ! -f index.md ]; then
echo "Creating index.md from README.md..."
cat > index.md << 'EOF'
---
layout: default
title: Home
description: Production-ready Model Context Protocol server for Google Cloud Dataproc operations
permalink: /
---
EOF
# Append README content without the first line (title)
tail -n +2 ../README.md >> index.md
fi
# Build with Jekyll
bundle exec jekyll build --destination ../_site
echo "📁 Jekyll build complete. Site structure:"
find ../_site -type f -name "*.html" | head -10
- name: Upload to GitHub Pages
uses: actions/upload-pages-artifact@v3
with:
path: _site
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
# Job 3: Documentation quality check
quality-check:
name: Documentation Quality Check
runs-on: ubuntu-latest
needs: generate-docs
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Download generated docs
uses: actions/download-artifact@v4
with:
name: generated-docs
path: docs/generated/
continue-on-error: true
- name: Generate docs if not downloaded
run: |
if [ ! -d "docs/generated" ] || [ -z "$(ls -A docs/generated 2>/dev/null)" ]; then
echo "📝 Generated docs not found, creating them..."
npm run docs:generate
else
echo "✅ Using downloaded generated docs"
fi
- name: Check documentation completeness
run: |
echo "📋 Checking documentation completeness..."
# Check for required documentation files
required_files=(
"docs/API_REFERENCE.md"
"docs/QUICK_START.md"
"docs/CONFIGURATION_EXAMPLES.md"
"docs/SECURITY_GUIDE.md"
"README.md"
)
missing_files=()
for file in "${required_files[@]}"; do
if [ ! -f "$file" ]; then
missing_files+=("$file")
fi
done
if [ ${#missing_files[@]} -gt 0 ]; then
echo "❌ Missing required documentation files:"
printf '%s\n' "${missing_files[@]}"
exit 1
else
echo "✅ All required documentation files present"
fi
- name: Check for broken internal links
run: npm run docs:test-links
- name: Validate documentation examples
run: npm run validate:examples
- name: Check documentation freshness
run: |
echo "📅 Checking documentation freshness..."
# Check if generated docs are up to date
npm run docs:generate
if git diff --quiet docs/generated/; then
echo "✅ Generated documentation is up to date"
else
echo "⚠️ Generated documentation may be outdated"
echo "Consider running 'npm run docs:generate' and committing changes"
fi
