sphinx.yml

name: sphinx
on: [push, pull_request]

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

jobs:
  build-and-deploy:
    name: Build and gh-pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
          lfs: false

      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.10"

      - name: Install MPI
        uses: mpi4py/setup-mpi@v1
        with:
          mpi: mpich

      - name: Install Poetry
        uses: snok/install-poetry@v1
        with:
          virtualenvs-create: true
          virtualenvs-in-project: true
          installer-parallel: true

      - name: Load cached venv
        id: cached-poetry-dependencies
        uses: actions/cache@v3
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/pyproject.toml') }}

      - name: Install dependencies
        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
        run: poetry install --no-interaction --with docs,assemble,dev

      - name: Debugging information
        run: |
          source .venv/bin/activate
          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
          python -V
          pip list --not-required
          pip list

      # Build
      - uses: ammaraskar/sphinx-problem-matcher@master
      - name: Build Sphinx docs
        working-directory: ./docs
        run: |
          source ../.venv/bin/activate
          make dirhtml
          # This fixes broken copy button icons, as explained in
          #   https://github.com/coderefinery/sphinx-lesson/issues/50
          #   https://github.com/executablebooks/sphinx-copybutton/issues/110
          # This can be removed once these PRs are accepted (but the
          # fixes also need to propagate to other themes):
          #   https://github.com/sphinx-doc/sphinx/pull/8524
          #   https://github.com/readthedocs/sphinx_rtd_theme/pull/1025
          sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true
      # The following supports building all branches and combining on
      # gh-pages

      # Clone and set up the old gh-pages branch
      - name: Clone old gh-pages
        if: ${{ github.event_name == 'push' }}
        working-directory: ./docs
        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/

      # If a push and default branch, copy build to _gh-pages/ as the "main"
      # deployment.
      - name: Copy new build (default branch)
        if: |
          contains(github.event_name, 'push') &&
          contains(github.ref, env.DEFAULT_BRANCH)
        working-directory: ./docs
        run: |
          set -x
          # Delete everything under _gh-pages/ that is from the
          # primary branch deployment.  Eicludes 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 _build/dirhtml/ _gh-pages/

      # If a push and not on default branch, then copy the build to
      # _gh-pages/branch/$brname (transforming '/' into '--')
      - name: Copy new build (branch)
        if: |
          contains(github.event_name, 'push') &&
          !contains(github.ref, env.DEFAULT_BRANCH)
        working-directory: ./docs
        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 _build/dirhtml/ _gh-pages/branch/${brdir}

      # Go through each branch in _gh-pages/branch/, if it's not a
      # ref, then delete it.
      - name: Delete old feature branches
        if: ${{ github.event_name == 'push' }}
        working-directory: ./docs
        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

      # Add the .nojekyll file
      - name: nojekyll
        if: ${{ github.event_name == 'push' }}
        working-directory: ./docs
        run: |
          touch _gh-pages/.nojekyll

      # Deploy
      # https://github.com/peaceiris/actions-gh-pages
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.event_name == 'push' }}
        #if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/$defaultBranch' }}
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_gh-pages/
          force_orphan: true