docs-deploy.yml

# This is for testing and getting at least basic docs builds out, but could
# be integrated into the central workflow later.

# The released docs are not versioned currently, only the latest ones are deployed.
# Versioning support would require either (better):
#   * Rebuilding docs for all versions when a new release is made
#   * Version selector support in `furo`: https://github.com/pradyunsg/furo/pull/500
# or (more basic):
#   * using the `gh-pages` branch and peaceiris/actions-gh-pages
#     to be able to deploy to subdirectories. The implementation via
#     actions/deploy-pages always replaces the directory root.

name: Publish Latest Documentation

on:
  push:
    branches:
      - 'main'

jobs:
  Docs:
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python 3.10 For Nox
        uses: actions/setup-python@v4
        with:
          python-version: "3.10"

      - name: Install Nox
        run: |
          python -m pip install --upgrade pip
          pip install nox

      - name: Install Doc Requirements
        run: |
          nox --force-color -e docs --install-only

      - name: Build Docs
        env:
          SKIP_REQUIREMENTS_INSTALL: YES
        run: |
          nox --force-color -e docs

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          name: html-docs
          path: docs/_build/html

  Deploy-Docs-GH-Pages:
    name: Publish Docs to GitHub Pages
    needs: Docs

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    permissions:
      pages: write
      id-token: write

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        with:
          artifact_name: html-docs