deploy-docs.yml

name: Build and Deploy Docs

env:
  POETRY_VERSION: "2.4.1"
  POETRY_DYNAMIC_VERSIONING_VERSION: "1.9.1"

on:
  push:
    branches:
      - main
  workflow_dispatch:
  workflow_run:
    workflows: ["Publish Python Package"]
    types: [completed]

permissions:
  contents: write

concurrency:
  group: docs-pages
  cancel-in-progress: false

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    if: >
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          fetch-tags: true
          ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.ref }}

      - name: Set up Python & Graphviz
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - uses: ts-graphviz/setup-graphviz@v2

      - name: Cache Poetry & pip
        uses: actions/cache@v3
        with:
          path: |
            ~/.cache/pypoetry
            ~/.cache/pip
          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}

      - name: Install Dependencies
        env:
          POETRY_DYNAMIC_VERSIONING_COMMANDS: install,build
        run: |
          pip install "poetry==${POETRY_VERSION}"
          poetry self add "poetry-dynamic-versioning[plugin]==${POETRY_DYNAMIC_VERSIONING_VERSION}"
          poetry install --with dev --extras docs

      - name: Debug Git state and version
        run: |
          echo "=== Git State ==="
          echo "Commit:     $(git rev-parse HEAD)"
          echo "Ref:        $GITHUB_REF"
          echo "Ref name:   $GITHUB_REF_NAME"
          echo "Exact tag?: $(git describe --tags --exact-match HEAD 2>/dev/null || echo 'none')"
          echo "Latest tag: $(git describe --tags --abbrev=0 2>/dev/null || echo 'none')"
          echo "=== Project Version ==="
          poetry version
          poetry run python -c 'import corneto; print(corneto.__version__)'

      - name: Determine version_folder
        id: set_version
        run: |
          if [ "${{ github.event_name }}" = "workflow_run" ]; then
            if [[ "${{ github.event.workflow_run.head_branch }}" == v* ]]; then
              echo "version_folder=${{ github.event.workflow_run.head_branch }}" >> $GITHUB_OUTPUT
            else
              echo "Publish workflow did not run for a release tag" >&2
              exit 1
            fi
          elif [ "${GITHUB_REF}" = "refs/heads/main" ]; then
            echo "version_folder=stable" >> $GITHUB_OUTPUT
          else
            echo "No documentation target for ${GITHUB_REF}" >&2
            exit 1
          fi

      - name: Sync GitHub Releases to Docs
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: python scripts/sync_releases.py --repo saezlab/corneto --docs-dir docs

      - name: Build Docs
        env:
          SPHINX_VERSION_MATCH: ${{ steps.set_version.outputs.version_folder }}
          DOCS_BASE_URL: https://corneto.org
        run: poetry run sphinx-build -W --keep-going -b html docs docs/_build/html

      - name: Check out gh-pages
        run: |
          set -euo pipefail
          git fetch origin gh-pages:refs/remotes/origin/gh-pages
          git worktree add --detach gh-pages-worktree refs/remotes/origin/gh-pages

      - name: Prepare Pages tree
        env:
          DOCS_BASE_URL: https://corneto.org
        run: |
          set -euo pipefail
          root_args=()
          if [ "${{ steps.set_version.outputs.version_folder }}" = "stable" ]; then
            root_args+=(--update-root)
          fi
          poetry run python scripts/prepare_docs_pages.py \
            --pages-dir gh-pages-worktree \
            --build-dir docs/_build/html \
            --landing-dir docs/landing \
            --version-folder "${{ steps.set_version.outputs.version_folder }}" \
            --base-url "${DOCS_BASE_URL}" \
            "${root_args[@]}"

      - name: Commit and deploy Pages tree
        env:
          VERSION_FOLDER: ${{ steps.set_version.outputs.version_folder }}
        run: |
          set -euo pipefail
          cd gh-pages-worktree
          if [ -z "$(git status --porcelain)" ]; then
            echo "No Pages changes to deploy."
            exit 0
          fi
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "docs: deploy ${VERSION_FOLDER}"
          git fetch origin gh-pages
          if ! git merge --ff-only origin/gh-pages; then
            echo "gh-pages advanced during deployment; refusing to overwrite it." >&2
            exit 1
          fi
          git push origin HEAD:gh-pages