deploy-docs.yml

name: Build and Deploy Docs

on:
  push:
    branches:
      - dev
      - main
    tags:
      - '*'
  workflow_dispatch:
    inputs:
      target:
        description: "What to build/deploy (dev=latest, main=stable, or tag)"
        type: choice
        required: true
        options:
          - dev
          - main
          - tag
      tag:
        description: "Tag to deploy when target=tag (e.g., v1.0.0-beta.3)"
        type: string
        required: false
  workflow_run:
    workflows: ["Publish Python Package"]
    types: [completed]

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_dispatch' &&
              (github.event.inputs.target == 'tag' && format('refs/tags/{0}', github.event.inputs.tag) ||
               format('refs/heads/{0}', github.event.inputs.target))
              || 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 self add "poetry-dynamic-versioning[plugin]"
          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: |
          case "${GITHUB_REF}" in
            refs/heads/dev)
              echo "version_folder=latest" >> $GITHUB_OUTPUT
              ;;
            refs/heads/main)
              echo "version_folder=stable" >> $GITHUB_OUTPUT
              ;;
            refs/tags/*)
              v="${GITHUB_REF#refs/tags/}"
              echo "version_folder=${v}" >> $GITHUB_OUTPUT
              ;;
            *)
              echo "No docs to deploy for ${GITHUB_REF}" >&2
              exit 0
              ;;
          esac

      - name: Sync GitHub Releases to Docs
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          sleep 30
          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 -b html docs docs/_build/html

      - name: Deploy “latest” docs
        if: ${{ steps.set_version.outputs.version_folder == 'latest' }}
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html
          destination_dir: latest
          keep_files: true

      - name: Deploy “stable” docs
        if: ${{ steps.set_version.outputs.version_folder == 'stable' }}
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html
          destination_dir: stable
          keep_files: true

      - name: Deploy versioned docs for tag
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html
          destination_dir: ${{ steps.set_version.outputs.version_folder }}
          keep_files: true

      - name: Prepare root redirect
        run: |
          mkdir -p temp_root
          touch temp_root/.nojekyll
          cp docs/custom-index.html temp_root/index.html
      - name: Generate switcher.json
        env:
          DOCS_BASE_URL: https://corneto.org
        run: |
          python scripts/generate_switcher.py --output temp_root/switcher.json

      - name: Deploy root redirect
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: temp_root
          destination_dir: ./
          keep_files: true

      - name: Patch switcher URL in published HTML
        run: |
          git fetch origin gh-pages
          git worktree add gh-pages-worktree gh-pages
          python scripts/patch_switcher_urls.py \
            --root gh-pages-worktree \
            --new-url https://corneto.org/switcher.json
          cd gh-pages-worktree
          if [ -n "$(git status --porcelain)" ]; then
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git add -A
            git commit -m "chore: update switcher json url"
            git push origin gh-pages
          else
            echo "No switcher URL changes detected."
          fi