_build_and_publish_documentation.yml

name: Build and publish documentation

on: workflow_call

env:
  DEFAULT_BRANCH: 'release'
  #SPHINXOPTS: '-W --keep-going -T'
  # ^-- If these SPHINXOPTS are enabled, then be strict about the builds and fail on any warnings

jobs:
  build-and-publish-docs:
    name: Build and publish documentation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout active branch
        uses: actions/checkout@v4
        with:
          lfs: true
      - name: Install uv
        uses: astral-sh/setup-uv@v2
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version-file: "pyproject.toml"
      - name: Install the project
        run: uv sync --upgrade
      - name: Print debugging information
        run: |
          echo "github.ref:" ${{github.ref}}
          echo "github.event_name:" ${{github.event_name}}
          echo "github.head_ref:" ${{github.head_ref}}
          echo "github.base_ref:" ${{github.base_ref}}
          set -x
          git rev-parse --abbrev-ref HEAD
          git branch
          git branch -a
          git remote -v
          uv run python -V
          uv pip list

      # Build documentation
      - uses: sphinx-doc/github-problem-matcher@master
      - name: Build documentation
        run: |
          cd docs
          uv run make html

      - name: Clone and cleanup gh-pages branch
        run: |
          set -x
          git fetch
          ( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
          rm -rf _gh-pages/.git/
          mkdir -p _gh-pages/branch/

      # Delete orphaned branch-folders:
      # Go through each subfolder in _gh-pages/branch/
      # If it relates to an orphaned branch, delete it.
      - name: Delete orphaned branch-folders
        run: |
          set -x
          for brdir in `ls _gh-pages/branch/` ; do
              brname=${brdir//--/\/}   # replace '--' with '/'
              if ! git show-ref remotes/origin/$brname ; then
                  echo "Removing $brdir"
                  rm -r _gh-pages/branch/$brdir/
              fi
          done

      # Copy documentation to _gh-pages/  (if push happened on release branch)
      - name: Copy documentation to _gh-pages/
        if: |
          contains(github.ref, env.DEFAULT_BRANCH)
        run: |
          set -x
          # Delete everything under _gh-pages/ that is from the
          # primary branch deployment.  Excludes the other branches
          # _gh-pages/branch-* paths, and not including
          # _gh-pages itself.
          find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' -delete
          rsync -a docs/build/html/ _gh-pages/

      # Copy documentation to _gh-pages/branch/$brname  (if push happened on any other branch)
      # ('/' gets replaced by '--')
      - name: Copy documentation to _gh-pages/branch/${{github.ref}}
        if: |
          !contains(github.ref, env.DEFAULT_BRANCH)
        run: |
          set -x
          #brname=$(git rev-parse --abbrev-ref HEAD)
          brname="${{github.ref}}"
          brname="${brname##refs/heads/}"
          brdir=${brname//\//--}   # replace '/' with '--'
          rm -rf   _gh-pages/branch/${brdir}
          rsync -a docs/build/html/ _gh-pages/branch/${brdir}

      # Add .nojekyll file
      - name: Add .nojekyll file
        run: touch _gh-pages/.nojekyll

      # Publish: Commit gh-pages branch and publish it to GitHub Pages
      - name: Publish documentation
        uses: peaceiris/actions-gh-pages@v4
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _gh-pages/
          force_orphan: true