docs.yml

name: Build and Deploy docs

on:
  push:
    branches: [ develop ]
  pull_request:
    branches: [ develop ]
  release:
    types:
      - created

jobs:
    docs:
      name: build and deploy docs
      # not using latest due to issues with pip user packages, see
      # https://github.com/actions/runner-images/issues/10781 and
      # https://github.com/actions/runner-images/issues/10636
      runs-on: ubuntu-22.04

      steps:
        - name: Checkout code
          uses: actions/checkout@v2
          with:
            fetch-depth: 0
        - name: Set system to non-interactive mode
          run: export DEBIAN_FRONTEND=noninteractive
        - name: install dependencies
          run: |
            pip install sphinx
            pip install sphinx-rtd-theme
            pip install sphinx-multiversion
        - name: build docs
          run: |
            echo "Repo = ${GITHUB_REPOSITORY}"
            cd doc/sphinx
            # throw warnings as error to make sure docs properly build
            make multiversion SPHINXOPTS="-W --keep-going -n"
        - name: Deploy
          if: ${{ (github.event.pull_request.head.repo.full_name == github.repository) || (github.ref == 'refs/heads/develop') }}
          uses: peaceiris/actions-gh-pages@v3.7.3
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: ./doc/sphinx/_build/html
            force_orphan: true