docs.yml

name: Deploy development docs

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: write

concurrency:
  group: docs-build-dev-${{ github.repository }}
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Resolve the site staging directory
        run: echo "SITE_DIR=$RUNNER_TEMP/httk-docs-site" >> "$GITHUB_ENV"

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          submodules: recursive
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Move all module checkouts to remote main
        run: |
          git submodule update --init --remote --recursive
          for submodule in submodules/*; do
            [ -d "$submodule" ] || continue
            git -C "$submodule" fetch origin main
            test "$(git -C "$submodule" rev-parse HEAD)" = "$(git -C "$submodule" rev-parse origin/main)" || {
              echo "$submodule is not at origin/main" >&2
              exit 1
            }
          done
          # The manifest checker validates index gitlinks against these dev pins.
          git add submodules/*
      - name: Verify aggregate source topology
        run: python scripts/verify_topology.py
      - name: Install locked external docs environment
        run: |
          # There are no internal pins in the aggregate lock.
          if [ -f docs/requirements.lock ]; then
            pip install -r docs/requirements.lock
          else
            echo "::warning::docs/requirements.lock is absent; using fresh external resolution"
          fi
          pip install -e submodules/httk-core --no-deps
          pip install -e submodules/httk-atomistic --no-deps
          pip install -e submodules/httk-analyse --no-deps
          pip install -e submodules/httk-io --no-deps
          pip install -e submodules/httk-data --no-deps
          pip install -e submodules/httk-serve --no-deps
          pip install -e submodules/httk-workflow --no-deps
          # Install the site extra after editable modules so only external dependencies resolve.
          pip install -e ".[docs]"
          pip check
      - name: Verify aggregate source resolution
        run: |
          PYTHONPATH="$GITHUB_WORKSPACE/submodules/httk-core/src:$GITHUB_WORKSPACE/submodules/httk-atomistic/src:$GITHUB_WORKSPACE/submodules/httk-analyse/src:$GITHUB_WORKSPACE/submodules/httk-io/src:$GITHUB_WORKSPACE/submodules/httk-data/src:$GITHUB_WORKSPACE/submodules/httk-serve/src:$GITHUB_WORKSPACE/submodules/httk-workflow/src" python - <<'PY'
          import importlib.util
          import os
          from pathlib import Path

          root = (Path(os.environ["GITHUB_WORKSPACE"]) / "submodules").resolve()
          for module in ("core", "atomistic", "analyse", "io", "data", "serve", "workflow"):
              spec = importlib.util.find_spec(f"httk.{module}")
              if spec is None or not spec.submodule_search_locations:
                  raise SystemExit(f"cannot resolve httk.{module}")
              location = Path(next(iter(spec.submodule_search_locations))).resolve()
              if root not in location.parents:
                  raise SystemExit(f"httk.{module} resolved outside submodules: {location}")
          PY
      - name: Generate development ecosystem manifest
        run: PYTHONPATH=submodules/httk-core/src python -m httk.core.docs ecosystem-manifest --submodules-dir submodules --out docs/ecosystem.json
      - name: Build development docs
        run: HTTK_DOCS_VERSION=dev:main HTTK_DOCS_BASE_URL=https://docs.httk.org make docs
      - name: Compose and publish development docs-site
        env:
          SOURCE_COMMIT: ${{ github.sha }}
        run: |
          remote_site_exists=false
          if git ls-remote --exit-code origin docs-site >/dev/null 2>&1; then remote_site_exists=true; git fetch origin docs-site; else status=$?; if [ "$status" -ne 2 ]; then exit 1; fi; fi
          for attempt in 1 2 3 4 5 6 7 8; do
            if [ "$remote_site_exists" = true ]; then lease_sha=$(git rev-parse origin/docs-site 2>/dev/null || echo ""); else lease_sha=""; fi
            rm -rf "$SITE_DIR"; mkdir -p "$SITE_DIR"
            if git show-ref --verify --quiet refs/remotes/origin/docs-site; then git archive origin/docs-site | tar -x -C "$SITE_DIR"; fi
            PYTHONPATH=submodules/httk-core/src python -m httk.core.docs compose --site "$SITE_DIR" --build docs/_build/html --dev --slug "" --url https://docs.httk.org --source-commit "$SOURCE_COMMIT"
            PYTHONPATH=submodules/httk-core/src python -m httk.core.docs commit-site --site "$SITE_DIR" --repo "$GITHUB_WORKSPACE" --branch docs-site --message "dev: $SOURCE_COMMIT"
            if git push --force-with-lease=refs/heads/docs-site:$lease_sha origin docs-site; then break; fi
            if [ "$attempt" -eq 8 ]; then echo "docs-site push was rejected after 8 attempts" >&2; exit 1; fi
            sleep $((RANDOM % 5 + attempt * 3)); git fetch origin docs-site; remote_site_exists=true
          done