docs.yml

name: Publish Sphinx Docs to GitHub Pages

on:
  # Build the docs on pushes to main branch, PRs to main branch, and new tags.
  # Publish only on demand.
  push:
    branches:
      - main
    tags:
      - "*" # all tags
  pull_request:
    branches:
      - main
  workflow_dispatch: # allow manual triggering
    inputs:
      deploy:
        description: "Deploy documentation"
        type: boolean
        required: true
        default: false

defaults:
  run:
    shell: bash -l {0}

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # otherwise, you will get "failed to push refs to dest repo"

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Deploy Information
        if: ${{ github.event.inputs.deploy }}
        run: |
          echo "The will be published from this workflow run."

      - name: Install pandoc
        run: |
          set -vxeuo pipefail
          sudo apt-get update && \
          sudo apt-get -y install pandoc

      - name: Install Sphinx build requirements
        run: |
          pip install -r docs/requirements.txt

      - name: Install our package
        run: |
          pip install --no-deps -e .

      - name: Diagnostic
        run: |
          echo $(which pandoc)
          echo $(which sphinx-build)

      - name: Make Temporary Directory for Sphinx content
        run: |
          echo "SRC_DIR=$(pwd)" >> ${GITHUB_ENV}
          echo "TMP_DIR=$(mktemp -d)" >> ${GITHUB_ENV}
          # next step also creates _version.py file
          echo "VERSION=$(python -m setuptools_scm)" >> ${GITHUB_ENV}

      - name: Show Environment variables
        run: |
          echo "SRC_DIR=${SRC_DIR}"
          echo "TMP_DIR=${TMP_DIR}"
          echo "VERSION=${VERSION}"

      - name: Sphinx
        run: |
          TZ=UTC sphinx-build -M html ./docs/source "${TMP_DIR}/build"

      - name: Build Info
        run: ls -lAFghR "${TMP_DIR}/build/html"

      - name: Upload Docs ZIP file as artifact
        uses: actions/upload-artifact@v4
        with:
          name: apstools-docs
          path: ${{ env.TMP_DIR }}/build/html

      - name: Re-build the master directory (contains all documentation versions)
        run: |
          set -vxeuo pipefail
          cp .github/index.html "${TMP_DIR}"

          cd "${TMP_DIR}"
          mv build/html "${VERSION}"
          /bin/rm -rf build
          ln -s "./${VERSION}" dev

          # add previous documentation (built versions)
          # update the switcher.json file before a new release
          wget https://github.com/BCDA-APS/apstools/archive/refs/heads/gh-pages.zip
          unzip -q gh-pages.zip
          /bin/rm gh-pages.zip

          source "${SRC_DIR}/.github/scripts/define_versions.sh"
          for v in ${versions}
            do
                if [ -d "apstools-gh-pages/${v}" ]
                  then
                      echo "directory 'apstools-gh-pages/${v}' exists"
                      mv "apstools-gh-pages/${v}" ./
                      latest="${v}"
                  fi
            done
          echo "latest=${latest}"
          ln -s "./${latest}" ./latest

          /bin/rm -rf apstools-gh-pages

      - name: Info
        run: |
          set -vxeuo pipefail
          cd "${TMP_DIR}"
          echo "pwd=$(pwd)"
          ls -laFGh
          du -shc *

      - name: Publish (push gh-pages branch) only on demand
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.event.inputs.deploy }}
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ${{ env.TMP_DIR }}
          force_orphan: true