docs.yml

name: API Docs

# Builds the API reference from the docstrings with pdoc and deploys it to
# GitHub Pages. One-time setup: Settings -> Pages -> Build and deployment ->
# Source: "GitHub Actions". Until then the build job still runs as a gate
# (it fails if the docstrings/imports don't produce docs) but the deploy job
# will be skipped/red.

on:
  push:
    branches: [master]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: '3.12'
      - name: Install package and dev dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"
      - name: Build API reference (pdoc)
        run: pdoc openbadgeslib -o site -d google
      # SHA-pinned: the Pages pipeline runs under the workflow's id-token: write.
      # Dependabot (.github/dependabot.yml) bumps the pin.
      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
        with:
          path: site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        # SHA-pinned (runs with id-token: write). Dependabot bumps the pin.
        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346  # v5