docs.yml

name: Documentation

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4

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

      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # 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

      - name: Upload built docs as artifact
        id: deployment
        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
        with:
          path: site
{% if cookiecutter.deploy_docs_to_github_pages %}
  deploy:
    environment:
      name: github-pages
      url: ${{ '{{' }} steps.deployment.outputs.page_url {{ '}}' }}
    permissions:
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    needs: build
    if: github.event_name != 'pull_request'
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
{%- endif %}