documentation.yml

defaults:
  run:
    shell: bash

on:  # Runs on any push event in a PR or any push event to master
  pull_request:
  push:
    branches:
      - 'main'

permissions: write-all

jobs:
  documentation:
    name: ${{ matrix.os }} / ${{ matrix.python-version }}
    
    runs-on: ${{ matrix.os }}
    
    strategy:
      matrix:  # only lowest supported Python on latest ubuntu
        os: [ubuntu-latest]
        python-version: [3.9]
    
    permissions:
      issues: write
      pull-requests: write
      contents: write
      pages: write

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'
          cache-dependency-path: '**/pyproject.toml'

      - name: Get full Python version
        id: full-python-version
        run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")

      - name: Upgrade pip, setuptools and wheel
        run: python -m pip install --upgrade pip setuptools wheel sphinx sphinx_rtd_theme

      - name: Install package
        run: python -m pip install '.[docs]'

      - name: Build documentation
        run: python -m sphinx -b html docs ./docs/_build -d ./docs/_build

      - name: Upload build artifacts  # upload artifacts so reviewers can have a quick look without building documentation from the branch locally
        uses: actions/upload-artifact@v4
        # if: success() && github.event_name == 'pull_request'  # only for pushes in PR
        with:
          name: site-build
          path: ./docs/_build
          retention-days: 5

      - name: Trigger RTDs build
        uses: dfm/rtds-action@v1
        with:
          webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
          webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
          commit_ref: ${{ github.ref }}

      - name: Upload documentation
        if: success() && github.ref == 'refs/heads/main'  # only for pushes to master
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          folder: docs/_build # The folder the action should deploy.

      # - name: Publish Docs to gh-pages
      #   uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847
      #   with:
      #     github_token: ${{ secrets.GITHUB_TOKEN }}
      #     publish_dir: docs/_build/html