python-docs.yml

name: Pip Build

on:
  workflow_call:
    inputs:
      package-name:
        description: "The Python-importable package name for which docs are being built"
        required: true
        type: string
      python-version:
        description: "The Python version to build and test with"
        default: "3.9"
        required: false
        type: string
      install-package:
        description: "Install the Python package prior to building documentation"
        required: false
        default: true
        type: boolean
      docs-template-repo:
        description: "Optional external repository holding the documentation template"
        required: false
        default: ""
        type: string
      docs-template-ref:
        description: "The ref to checkout for the template repo"
        default: "master"
        required: false
        type: string
      docs-directory:
        default: "docs/"
        description: "The documentation directory"
        required: false
        type: string
      docs-build-directory:
        default: "build/html"
        description: "The directory where built documentation will be, relative to docs-directory"
        required: false
        type: string
      experimental:
        description: "Mark this version as experimental and not required to pass"
        required: false
        default: false
        type: boolean
      deploy:
        description: "Deploy the documentation to the gh-pages branch if successfully built"
        required: false
        default: false
        type: boolean
      docs-extras:
        default: ""
        description: "Extra packages to be installed for documentation"
        required: false
        type: string
      system-packages:
        default: ""
        description: "CI-specific system packages required for docs building"
        required: false
        type: string
    outputs: {}

env:
  MPLBACKEND: "agg"
  QT_QPA_PLATFORM: "offscreen"

jobs:
  build:
    name: "Python ${{ inputs.python-version }}: documentation building"
    runs-on: ubuntu-20.04
    continue-on-error: ${{ inputs.experimental }}

    defaults:
      run:
        # The following allows for each run step to utilize ~/.bash_profile
        # for setting up the per-step initial state.
        # --login: a login shell. Source ~/.bash_profile
        # -e: exit on first error
        # -o pipefail: piped processes are important; fail if they fail
        shell: bash --login -eo pipefail {0}

    outputs:
      deploy_version: ${{ steps.version.outputs.built_docs_version }}

    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
        submodules: 'recursive'

    - uses: actions/checkout@v4
      if: inputs.docs-template-repo != ''
      with:
        repository: ${{ inputs.docs-template-repo }}
        ref: ${{ inputs.docs-template-ref }}
        path: ${{ inputs.docs-directory }}
        submodules: 'recursive'

    - name: Check that the documentation directory exists
      run: |
        if [ ! -d "${{ inputs.docs-directory}}" ]; then
          echo "Documentation directory '${{ inputs.docs-directory}}' does not exist!" \
            | tee "$GITHUB_STEP_SUMMARY"
          exit 1
        fi

    - name: Check version tag for deployment
      id: version
      shell: bash -l {0}
      run: |
        if [[ "$GITHUB_EVENT_NAME" == "pull_request" ]]; then
          # It may be a PR against a non-master branch, but that doesn't matter here.
          version="master"
        elif [[ "$GITHUB_EVENT_NAME" == "push" && "${{ github.ref }}" = refs/heads/* ]]; then
          # If this is a push to a branch, then use that branch name.
          # `basename refs/heads/a` -> "a"
          version="$(basename "${{ github.ref }}")"
        else
          # For refs/tags and anything else, use the version from git.
          version="$(git describe --tags)"
        fi
        (
          echo "Package version: $(git describe --tags)"
          echo "Documentation version name: ${version}"
        ) | tee "$GITHUB_STEP_SUMMARY"

        echo "built_docs_version=${version}" >> $GITHUB_OUTPUT

    - name: Check environment variables for issues
      run: |
        echo "* Package to be built: ${{ inputs.package-name }}"
        echo "* Pip 'extras' for documentation: ${{ inputs.docs-extras }}"
        echo "* General pip packages required for documentation: ${{ inputs.docs-extras }}"

        if [ -z "${{ steps.version.outputs.built_docs_version }}" ]; then
          echo "Built docs version unset? See previous step"
          exit 1
        fi

    - name: Install required system packages
      if: inputs.system-packages != ''
      run: |
        sudo apt-get update
        sudo apt-get -y install ${{ inputs.system-packages }}

    - name: Prepare for log files
      run: |
        mkdir $HOME/logs

    - uses: actions/setup-python@v5
      with:
        python-version: '${{ inputs.python-version }}'

    - name: Upgrade pip
      run: |
        pip install --upgrade pip

    - name: Installing package
      if: ${{ inputs.install-package }}
      run: |
        pip install .[test,doc]

    - name: Installing documentation extras
      run: |
        # 1. escape '<' so the user doesn't have to
        # 2. escape '>' so the user doesn't have to
        # 3. allow conda/pip to use the same requirements spec;
        # conda expects pkg=ver but pip expects pkg==ver; using a basic
        # (not =<>)=(not =) to avoid incompatibility with macOS sed not supporting
        # '=\+'
        #
        if [ -n "${{ inputs.docs-extras }}" ]; then
          input_requirements=$(
            echo "${{ inputs.docs-extras }}" |
            sed -e "s/</\</g" |
            sed -e "s/>/\>/g" |
            sed -e 's/\([^=<>]\)=\([^=]\)/\1==\2/g'
          )

          declare -a docs_requirements=()
          for req in $input_requirements; do
            docs_requirements+=( "$req" )
          done
          set -x
          pip install "${docs_requirements[@]}"
        else
          echo "No extras to install."
        fi

    - name: Check the pip packages in the test env
      run: |
        pip list

    - name: Build documentation
      run: |
        cd "${{ inputs.docs-directory }}"
        make html 2>&1 | tee $HOME/logs/docs-build.txt

    - name: Upload documentation as artifact
      uses: actions/upload-artifact@v4
      with:
        name: Python ${{ inputs.python-version }} - documentation
        path: "${{ inputs.docs-directory }}/${{ inputs.docs-build-directory }}"

    - name: Upload log file artifacts
      if: ${{ always() }}
      uses: actions/upload-artifact@v4
      with:
        name: Python ${{ inputs.python-version }} - documentation - logs
        path: "~/logs"

  deploy:
    name: "Documentation deployment"
    runs-on: ubuntu-20.04
    needs: build
    if: ${{ inputs.deploy }}

    permissions:
      # to deploy to Pages
      pages: write
      # push to repo gh-pages branch (*gasp*; is there a better way?)
      contents: write
      # deployments: write
      # to verify the deployment originates from an appropriate source
      id-token: write

    defaults:
      run:
        # The following allows for each run step to utilize ~/.bash_profile
        # for setting up the per-step initial state.
        # --login: a login shell. Source ~/.bash_profile
        # -e: exit on first error
        # -o pipefail: piped processes are important; fail if they fail
        shell: bash --login -eo pipefail {0}

    environment:
      name: gh-pages
      # url: ${{ steps.build-and-deploy.outputs.page_url }}

    steps:
    - uses: actions/setup-python@v5
      with:
        python-version: '${{ inputs.python-version }}'

    - name: Upgrade pip
      run: |
        pip install --upgrade pip

    - name: Installing documentation upload requirements
      run: |
        pip install docs-versions-menu

    - name: Download documentation artifact
      uses: actions/download-artifact@v4
      with:
        name: Python ${{ inputs.python-version }} - documentation

    - name: Configure git for docs deployment
      run: |
        git config --global user.name github-actions
        git config --global user.email github-actions@github.com
        git config --global init.defaultBranch gh-pages

    - name: List cached documentation
      run: |
        ls -lR

    - name: Update documentation with docs-versions-menu
      run: |
        # Adapted from docs-versions-menu workflow and my old caproto attempt:
        # - https://github.com/goerz/docs_versions_menu/blob/master/.github/workflows/docs.yml
        # - https://github.com/caproto/caproto/blob/master/.github/workflows/docs.yml
        set -x
        git clone --branch gh-pages https://github.com/${{ github.repository }} "$HOME/gh-pages" || (
          mkdir "$HOME/gh-pages"
          cd "$HOME/gh-pages"
          git init
        )
        rsync -av --delete ./ "$HOME/gh-pages/${{ needs.build.outputs.deploy_version }}/"

        # Run docs-versions-menu
        cd "$HOME/gh-pages"
        docs-versions-menu

    - name: Commit updated documentation to gh-pages
      run: |
        cd "$HOME/gh-pages"

        git add --all --verbose
        git status

        if ! git rev-parse HEAD &>/dev/null ; then
          git commit --verbose \
            -m "Initial commit of documentation" \
            -m "Deployed from commit ${GITHUB_SHA} (${GITHUB_REF})"
        else
          commit_message_file="$HOME/documentation_commit_message.txt"
          echo "The commit message will be:"
          echo "---------------------------"
          git log --format=%B -n 1 | tee "${commit_message_file}"
          echo "---------------------------"
          last_log_line=$(cat "${commit_message_file}" | grep -v '^$' | tail -n1)
          last_author=$(git log --format=%an -n 1)
          echo "Last log line: ${last_log_line}"
          echo "Last author: ${last_author}"
          echo "Current ref: ${{ github.ref }}"
          if [[ "$last_author" == "github-actions"* && "$last_log_line" == *"${{ github.ref }}"* ]]; then
            # Amend if the previous commit was done by Actions and was based on the same branch/tag name
            echo "Amending previous commit"
            echo "Deployed from commit ${GITHUB_SHA} (${GITHUB_REF})" >> "${commit_message_file}"
            git commit --verbose --amend --file="${commit_message_file}"
          else
            echo "Making new commit"
            git commit --verbose \
              -m "Auto-update from Github Actions Workflow" \
              -m "Deployed from commit ${GITHUB_SHA} (${GITHUB_REF})" ||
                echo "Documentation unchanged"
          fi
        fi
        git log -n 2 --stat

    - name: Pushing documentation
      if: ${{ inputs.deploy }}
      run: |
        cd "$HOME/gh-pages"
        # --force-with-lease=gh-pages
        git push --verbose \
          --force \
          "https://${GITHUB_ACTOR}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}" \
          gh-pages