docs.yml

name: Documentation

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4

      - name: Cache tox
        uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4
        with:
          path: .tox
          key: tox-${{ hashFiles('pyproject.toml') }}

      - name: Set up Python
        uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5
        with:
          python-version: "3.x"
          cache: "pip"
          cache-dependency-path: "pyproject.toml"

      - name: Install tox
        run: python -m pip install tox
      - name: Build HTML documentation with tox
        run: tox -e docs

      # Automatically deploy documentation to a GitHub Pages website on pushing to main.
      # Requires configuring the repository to deploy GitHub pages from a branch
      # gh-pages (https://tinyurl.com/gh-pages-from-branch), which will be created the
      # first time this workflow step is run.
      - name: Publish documentation on GitHub pages
        if: success() && github.event_name != 'pull_request'
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
        with:
          github_token: ${{  secrets.GITHUB_TOKEN }}
          publish_dir: site
          publish_branch: gh-pages
          user_name: "github-actions[bot]"
          user_email: "github-actions[bot]@users.noreply.github.com"