deploy.yml

name: Deploy MkDocs site to GitHub Pages

# Runs for:
# - pushes to main: build -> commit generated files -> deploy
# - PRs into main: build/validate only (no commits, no deploy)
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

# --------------------------------------------------------------------------------------
# Default shell behavior for ALL `run:` steps (both jobs)
#
# Why this:
# - GitHub's built-in `bash` already uses: `bash --noprofile --norc -eo pipefail {0}`
#   which is effectively "fail fast" for bash scripts.
# - We add `-u` for extra safety: referencing unset variables becomes an error.
# - `--noprofile --norc` prevents unexpected user-profile side effects.
# - `pipefail` ensures a failing command inside a pipeline fails the step.
# --------------------------------------------------------------------------------------
defaults:
  run:
    shell: bash --noprofile --norc -euo pipefail {0}

# Prevent overlapping runs on the same ref from stepping on each other (e.g., deploy pushes).
# If you push multiple commits quickly, older runs for the same branch are canceled.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Default least-privilege; PRs only need read
permissions:
  contents: read

jobs:
  build:
    name: Build & validate (PRs and main)
    runs-on: ubuntu-latest
    steps:
      # --- Checkout repo files so we can build & run scripts ---
      - name: Checkout repository
        uses: actions/checkout@v6

      # --- Install Python with pip cache for faster subsequent runs ---
      - name: Set up Python 3.x with pip cache
        uses: actions/setup-python@v6
        with:
          python-version: "3.13"
          cache: pip
          cache-dependency-path: scripts/requirements-deploy.txt

      # --- Install all required Python packages for docs & tooling ---
      - name: Install Python dependencies
        run: pip install -r scripts/requirements-deploy.txt

      # --- Clean up repo-specific detritus before generating docs ---
      - name: Clean unwanted files
        run: python scripts/clean-unwanted-files.py

      # --- OWL post-processing (latest versioned pair): labels, synonyms, packages, stages, isDefinedBy, comment cleanup ---
      - name: OWL post-processing (labels, packages, maturity)
        run: python scripts/owl-postprocess.py

      # --- Ensure ontology metadata is present/updated (gUFO file) ---
      - name: Ensure metadata is added to gUFO file
        run: python scripts/insert-metadata.py

      # --- Promote newest versioned files into 'latest' folder ---
      - name: Move newest files from versioned to latest
        run: python scripts/move-latest.py

      # --- Copy ontology changelog into docs so it appears on the MkDocs site ---
      - name: Copy ontology changelog into docs
        run: |
          mkdir -p docs/deliverables
          cp ontologies/changelog-ontology.md docs/deliverables/changelog-ontology.md

      # --- Ensure no stale PyLODE HTML / docs remain (forces regeneration) ---
      - name: Forces clean sync
        run: |
          rm -f docs/deliverables/specification-ontology.html
          rm -f docs/method/specification-vocabulary.html
          rm -f docs/deliverables/documentation.md

      # --- Refresh images in docs from latest ontology assets ---
      # Robust variant:
      # - avoids glob failures when folders are empty or missing
      # - ensures destination exists before copy
      - name: Replace ontology images in docs with latest
        run: |
          rm -rf docs/deliverables/assets/images
          mkdir -p docs/deliverables/assets/images
          cp -r ontologies/latest/images/. docs/deliverables/assets/images/

      # --- Generate OntoUML documentation (custom script) ---
      - name: Generate OntoUML documentation
        run: python scripts/docgen-ontouml.py

      # --- Generate PyLODE HTML specs for ontology and vocabulary ---
      - name: Generate PyLODE specifications
        run: python scripts/docgen-pylode.py

      # --- Convert SSSOM TSV to TTL (kept in repo + used in site) ---
      - name: Create TTL serialization of SSSOM TSV
        run: python scripts/sssom-tsv2ttl.py

      # --- Include SSSOM TSV in built site (docs static assets) ---
      - name: Copy SSSOM TSV into docs assets
        run: |
          mkdir -p docs/deliverables/assets
          cp mappings/health-ri-mappings.tsv docs/deliverables/assets/health-ri-mappings.tsv

      # --- Remove comments from public copy of TSV in docs assets ---
      - name: Strip commented lines from public TSV copy
        run: sed -i '/^#/d' docs/deliverables/assets/health-ri-mappings.tsv

      # --- Validate MkDocs config before full build (fast fail) ---
      - name: Validate MkDocs configuration
        run: mkdocs build --verbose --clean --site-dir /tmp/mkdocs-check

      # --- Build MkDocs site into ./site ---
      - name: Build MkDocs site
        run: mkdocs build

      # --- Check internal links (ignore ephemeral hash-like URLs) ---
      - name: Check links in built site
        run: |
          linkchecker ./site \
            --no-status \
            --ignore-url="n[0-9a-f]{32,}"

      # --- Upload built site as artifact for deploy job ---
      - name: Upload built site artifact
        uses: actions/upload-artifact@v7
        with:
          name: site
          path: site
          retention-days: 7

      # --- Upload generated content that should be committed on main ---
      # This keeps the repo’s generated artifacts (ontologies, vocabulary, mappings, specs) up-to-date.
      - name: Upload generated content artifact (to commit on main)
        uses: actions/upload-artifact@v7
        with:
          name: generated
          path: |
            ontologies/versioned/**
            ontologies/latest/**
            vocabulary/versioned/**
            vocabulary/latest/**
            mappings/**
            docs/deliverables/assets/health-ri-mappings.tsv
            docs/deliverables/specification-ontology.html
            docs/method/specification-vocabulary.html
          retention-days: 7

  deploy:
    name: Commit generated files & publish (main only)
    needs: build
    runs-on: ubuntu-latest

    # Only run on direct pushes to main (not PRs)
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'

    # Needs write permission to commit and push changes
    permissions:
      contents: write

    steps:
      # --- Checkout the exact commit that triggered this workflow run ---
      - name: Checkout repository
        uses: actions/checkout@v6

      # --- Retrieve generated files produced by the build job ---
      - name: Download generated content artifact
        uses: actions/download-artifact@v8
        with:
          name: generated
          path: .

      # --- Retrieve the already-built site folder ---
      - name: Download built site artifact
        uses: actions/download-artifact@v8
        with:
          name: site
          path: ./site

      # --- Commit any changes from generation (idempotent) ---
      - name: Commit and push generated files (if there are changes)
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          shopt -s globstar

          git add ontologies/versioned/** ontologies/latest/** || true
          git add vocabulary/versioned/** vocabulary/latest/** || true
          git add mappings/** || true
          git add docs/deliverables/assets/health-ri-mappings.tsv || true
          git add docs/deliverables/specification-ontology.html || true
          git add docs/method/specification-vocabulary.html || true

          # If nothing is staged, do nothing; otherwise commit + push.
          git diff --cached --quiet || git commit -m "docs: update generated documentation and specifications"

          # Future-proof: push back to the branch that triggered the run (here: main).
          git push origin "HEAD:${GITHUB_REF_NAME}"

      # --- Publish the built site to GitHub Pages from ./site ---
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site