build-docs.yaml

name: Build documentation

on:
  workflow_dispatch: # run on request (no need for PR)

  push:
    branches:
      - main
    paths-ignore:
      - ".github/**" # Ignore changes towards the .github directory

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build_docs:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@a4aa98b93cab29d9b1101a6143fb8bce00e2eac4 # v2.7.1
        with:
          egress-policy: audit

      - name: Checkout repository
        uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0

      - name: Set up Python
        uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # v4.7.1
        with:
          python-version: 3.9

      - name: Install package with dev, notebooks and docs requirements
        run: |
          pip install ".[dev,notebooks]" --pre
          pip install -r requirements/requirements-docs.txt

      - name: Build sphinx documentation
        # We build twice to ensure that all references are resolved
        run: |
          cd docs
          make html
          make html
          cd ..

      - name: Clean up repo directory
        run: |
          mkdir -p /tmp/docs_build
          cp -r docs/build/html/* /tmp/docs_build
          rm -rf ./*
          # git fetch && git pull
          # git checkout gh-pages
          cp -r /tmp/docs_build/* ./
          rm -rf /tmp/docs_build
          touch .nojekyll
          # git config --local user.email "action@github.com"
          # git config --local user.name "GitHub Action"
          # git add .
          # git commit -m "Update documentation" -a || true
          # The above command will fail if no changes were present, so we ignore
          # the return code.

      - name: Setup Pages
        uses: actions/configure-pages@c5a3e1159e0cbdf0845eb8811bd39e39fc3099c2 # v2.1.3

      - name: Upload artifact
        uses: actions/upload-pages-artifact@84bb4cd4b733d5c320c9c9cfbc354937524f4d64 # v1.0.10
        with:
          # Upload entire repository
          path: '.'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@f27bcc15848fdcdcc02f01754eb838e44bcf389b # v1.2.9