Add docs build #1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: docs | |
| on: | |
| push: | |
| #tags: [ 'v*', 'release-*' ] | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: pages | |
| cancel-in-progress: true | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 # required for sphinx-multiversion to see history | |
| fetch-tags: true | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.10' | |
| - name: Install doc build deps | |
| run: | | |
| pipenv --python 3.10 install -e ".[dev]" | |
| pipenv --python 3.10 install -e ".[data]" ".[airflow]" ".[aisystems]" | |
| - name: Build multi-version docs | |
| run: pipenv run sphinx-build -M html source docs_build | |
| - name: Assemble site and landing page | |
| shell: bash | |
| run: | | |
| set -euo pipefail | |
| mkdir -p site | |
| rsync -a docs_build/html/ site/ | |
| # Determine latest branch dir (prefer main, else master) | |
| LATEST_BRANCH="" | |
| if [ -d site/main ]; then LATEST_BRANCH="main"; fi | |
| if [ -z "$LATEST_BRANCH" ] && [ -d site/master ]; then LATEST_BRANCH="master"; fi | |
| # Determine stable tag dir (prefer semantic v*, else Release-*) | |
| STABLE_TAG="" | |
| TAG_CANDIDATE=$(git tag -l | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n1 || true) | |
| if [ -n "$TAG_CANDIDATE" ] && [ -d "site/$TAG_CANDIDATE" ]; then | |
| STABLE_TAG="$TAG_CANDIDATE" | |
| else | |
| TAG_CANDIDATE=$(git tag -l | grep -E '^(Release|release)-[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n1 || true) | |
| if [ -n "$TAG_CANDIDATE" ] && [ -d "site/$TAG_CANDIDATE" ]; then | |
| STABLE_TAG="$TAG_CANDIDATE" | |
| fi | |
| fi | |
| # Fallbacks if not found | |
| [ -z "$LATEST_BRANCH" ] && LATEST_BRANCH="." | |
| [ -z "$STABLE_TAG" ] && STABLE_TAG="$LATEST_BRANCH" | |
| # Collect available versions (directories with an index.html) | |
| BRANCHES=() | |
| TAGS=() | |
| for d in site/*; do | |
| [ -d "$d" ] || continue | |
| name=$(basename "$d") | |
| [ -f "$d/index.html" ] || continue | |
| if [ "$name" = "main" ] || [ "$name" = "master" ]; then | |
| BRANCHES+=("$name") | |
| elif echo "$name" | grep -Eq '^(v[0-9]+\.[0-9]+\.[0-9]+|(R|r)elease-[0-9]+\.[0-9]+\.[0-9]+)$'; then | |
| TAGS+=("$name") | |
| else | |
| # Unknown grouping; treat as branch-like | |
| BRANCHES+=("$name") | |
| fi | |
| done | |
| # Sort tags in descending version order | |
| if [ ${#TAGS[@]} -gt 0 ]; then | |
| IFS=$'\n' TAGS=($(printf '%s\n' "${TAGS[@]}" | sort -Vr)); unset IFS | |
| fi | |
| # Create a landing page linking to latest, stable, and all versions | |
| cat > site/index.html <<HTML | |
| <!doctype html> | |
| <html lang="en"> | |
| <head> | |
| <meta charset="utf-8"> | |
| <meta name="viewport" content="width=device-width, initial-scale=1"> | |
| <title>python-domino Documentation</title> | |
| <style> | |
| body { font: 16px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; padding: 2rem; color: #222; } | |
| h1 { margin-bottom: .25rem; } | |
| p.sub { color: #555; margin-top: 0; } | |
| .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 1rem; margin-top: 1rem; } | |
| .card { border: 1px solid #e5e5e5; border-radius: 8px; padding: 1rem; } | |
| .btn { display: inline-block; padding: .5rem .75rem; border-radius: 6px; text-decoration: none; color: #fff; background: #2c7be5; } | |
| .btn.secondary { background: #6c757d; } | |
| .muted { color: #666; font-size: .9em; } | |
| .cols { display: grid; grid-template-columns: 1fr; gap: 1rem; margin-top: 2rem; } | |
| @media (min-width: 860px) { .cols { grid-template-columns: 1fr 1fr; } } | |
| ul { margin: .5rem 0 0; padding-left: 1.25rem; } | |
| </style> | |
| </head> | |
| <body> | |
| <h1>python-domino Docs</h1> | |
| <p class="sub">Browse the latest development docs, the latest stable release, or any specific version.</p> | |
| <div class="grid"> | |
| <div class="card"> | |
| <h3>Latest</h3> | |
| <p class="muted">Built from the default branch.</p> | |
| <p><a class="btn" href="${LATEST_URL}">Open Latest</a></p> | |
| </div> | |
| <div class="card"> | |
| <h3>Stable</h3> | |
| <p class="muted">Built from the most recent version tag.</p> | |
| <p><a class="btn secondary" href="${STABLE_URL}">Open Stable</a></p> | |
| </div> | |
| </div> | |
| <div class="cols"> | |
| <div class="card"> | |
| <h3>Branches</h3> | |
| <ul> | |
| HTML | |
| for name in "${BRANCHES[@]}"; do | |
| echo " <li><a href=\"${name}/\">${name}</a></li>" >> site/index.html | |
| done | |
| cat >> site/index.html <<'HTML' | |
| </ul> | |
| </div> | |
| <div class="card"> | |
| <h3>Tags</h3> | |
| <ul> | |
| HTML | |
| for name in "${TAGS[@]}"; do | |
| echo " <li><a href=\"${name}/\">${name}</a></li>" >> site/index.html | |
| done | |
| cat >> site/index.html <<'HTML' | |
| </ul> | |
| </div> | |
| </div> | |
| <p class="muted">You can also switch versions from the menu on any docs page.</p> | |
| </body> | |
| </html> | |
| HTML | |
| - name: Configure Pages | |
| uses: actions/configure-pages@v5 | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: site | |
| deploy: | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| needs: build | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |