deploy-docs-action.yml

---
name: Publish Documentation

on:
  workflow_call:
    inputs:
      # This is the name of the regular artifact that should
      # be transformed into a GitHub Pages deployment.
      artifact-name:
        type: string
        required: false
        default: html-docs

jobs:

  # 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.

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

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

    permissions:
      pages: write
      id-token: write

    runs-on: ubuntu-24.04

    steps:
      - name: Download built docs
        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16  # v4.1.8
        with:
          name: ${{ inputs.artifact-name }}
          path: html-docs

      - name: Upload GitHub Pages artifact
        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa  # v3.0.1
        with:
          name: html-docs-pages
          path: html-docs

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e  # v4.0.5
        with:
          artifact_name: html-docs-pages

      - name: Delete GitHub Pages artifact
        if: always()
        uses: geekyeggo/delete-artifact@7ee91e82b4a7f3339cd8b14beace3d826a2aac39  # v5.1.0
        with:
          name: html-docs-pages
          failOnError: false

      - name: Set Exit Status
        if: always()
        run: |
          mkdir exitstatus
          echo "${{ job.status }}" > exitstatus/${{ github.job }}

      - name: Upload Exit Status
        if: always()
        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882  # v4.4.3
        with:
          name: exitstatus-${{ github.job }}
          path: exitstatus
          if-no-files-found: error