documentation.yaml

name: pypop.org website and docs generation

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

on:
  workflow_dispatch:
  push:
    paths: &docs_paths
      - '*.rst'
      - 'NEWS.md'
      - 'LICENSE'
      - 'pypop-logo.png'
      - 'website/**'
      - 'src/PyPop/**'
      - 'tests/data/doc-examples/**'
      - 'src/script_build/generate_metadata.py'
      - '.github/workflows/documentation.yaml'
      - '!website/_templates/announcement_banner.html'
      - '!website/README.md'
      - '!website/reference/**'
  pull_request:
    paths: *docs_paths
  release:
    types:
      - published


permissions:
  contents: write
jobs:
  docs_check:
    runs-on: ubuntu-latest
    outputs:
      docs_rebuild: ${{ steps.changes.outputs.docs_rebuild }}
    steps:
      - name: Checkout full repo history
        uses: actions/checkout@v6
        with:
          fetch-depth: 0  # fetch full history so we can diff branches
      - name: Detect changed files
        id: changes
        run: |
          set -x
          git diff --name-only 'HEAD^'
          changed_files=$(git diff --name-only HEAD^)

          # Skip rebuild only if there are changes and all are under src/PyPop/
          if [[ "${GITHUB_REF}" == "refs/heads/main" ]] && [[ -n "$changed_files" ]] && \
             ! echo "$changed_files" | grep -qv '^src/PyPop/'; then
              echo "Skipping docs rebuild!"
              echo "docs_rebuild=false" >> "$GITHUB_OUTPUT"
          else
              echo "Doing docs rebuild!"
              echo "docs_rebuild=true" >> "$GITHUB_OUTPUT"
          fi

  docs:
    runs-on: ubuntu-latest
    needs: docs_check
    if: needs.docs_check.outputs.docs_rebuild == 'true'
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Check GitHub Action permissions
        run: |
          echo "github.actor:  ${{ toJson(github.actor) }}"
          echo "github.triggering_actor:  ${{ toJson(github.triggering_actor) }}"
          echo "github.repository_owner:  ${{ toJson(github.repository_owner) }}"
          echo "github.repository_owner:  ${{ toJson(github.repository_owner) }}"
          echo "github.repository: ${{ toJson(github.repository) }}"
          echo "github.event.pull_request.base.repo.full_name: ${{ toJson(github.event.pull_request.base.repo.full_name) }}"
          echo "github.event.pull_request.head.repo.full_name: ${{ toJson(github.event.pull_request.head.repo.full_name) }}"
          echo "github.ref: ${{ toJson(github.ref) }}"
          echo "github.event_name: ${{ toJson(github.event_name) }}"
          echo "github.event.action: ${{ toJson(github.event.action) }}"
          echo "github.event.release.target_commitish: ${{ toJson(github.event.release.target_commitish) }}"

      - uses: actions/setup-python@v6

      - name: Install Python deps + graphviz for API diagrams
        run: |
          # shared dependencies
          pip install -r website/requirements-docs.txt
          sudo apt-get install -y --no-install-recommends graphviz

      - name: Determine AutoAPI source + version metadata
        id: select-autoapi
        run: |
          mode="internal"
          if [[ "${GITHUB_REF}" == "refs/heads/main" ]]; then
             echo "Detected main branch (non-release): using installed package"
             mode="installed"
             echo "PYPOP_DOCS_MODE=$mode" >> "$GITHUB_ENV"
             pip install pypop-genomics[test]  # only needed in this mode
             # test current user guide again released API
             sphinx-build -b doctest website/doctest/ _doctests
          else
             echo "Using internal source (tag or branch build)"
             echo "PYPOP_DOCS_MODE=$mode" >> "$GITHUB_ENV"
             # needed because tomli is used for backwards compatibility
             pip install tomli
             #  in the internal case we generate _metadata.py manually
             #  since we are not doing a `pip install` build
             python src/script_build/generate_metadata.py src/PyPop/_metadata.py
          fi

      - name: Build LaTeX sources
        run: |
          # latex build in separate directory
          # it generates a lot of files we don't need to keep
          sphinx-build -b latex website _latexbuild
      # Compile PDF (auto-detects the versioned .tex file)
      - name: Compile PDF
        uses: xu-cheng/latex-action@v4
        with:
          working_directory: _latexbuild
          root_file: |
            pypop-guide-*.tex
            pypop-api-*.tex
          docker_image: ghcr.io/xu-cheng/texlive-debian:20250701
      - name: Postprocess PDF
        run: |
          # create _build directory and move the PDFs there
          mkdir _build
          cp _latexbuild/pypop-*.pdf _build/
          # create a symlink from 'pypop-guide.pdf' to the latest version
          cd _build/
          ln -s pypop-guide*.pdf pypop-guide.pdf
          ln -s pypop-api*.pdf pypop-api.pdf
          cd -
      - name: Build HTML
        run: |
          # now build the HTML
          sphinx-build website _build

      - name: Deploy to beta site
        uses: peaceiris/actions-gh-pages@v4.1.0
        # only update beta site if base and head branches match, not for forks
        # forks cannot access secrets to deploy, see: https://github.com/orgs/community/discussions/26829
        # also dependabot jobs won't work either
        if: ${{ (github.event.pull_request.base.repo.full_name == github.event.pull_request.head.repo.full_name) && github.actor != 'dependabot[bot]' }}
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: alexlancaster/beta.pypop.org
          publish_branch: gh-pages  # default: gh-pages
          publish_dir: _build/
          force_orphan: true

      - name: Deploy to production
        uses: peaceiris/actions-gh-pages@v4
        # only update on either a push on main, or published release on the main
        if: ${{ (github.ref == 'refs/heads/main' && github.event_name == 'push') || (github.event.release.target_commitish == 'main' && github.event_name == 'release' && github.event.action == 'published') }}
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _build/
          force_orphan: true