docs.yml

name: Docs

on:
  # Publishes rustdoc to GitHub Pages on every push to main.
  # TODO(template) This REQUIRES GitHub Pages enabled (Settings -> Pages -> Source:
  # GitHub Actions); until you enable it these runs will fail. If you publish the crate
  # to crates.io instead, delete this workflow and use the docs.rs badge in the README.
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

jobs:
  # TODO(template) remove docs publishing, when the crate is published to crates.io
  docs:
    name: Documentation
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Checkout source code
        uses: actions/checkout@v4
        with:
          fetch-depth: 1
          persist-credentials: false

      - uses: dtolnay/rust-toolchain@stable

      - uses: Swatinem/rust-cache@v2

      - name: Setup pages
        id: pages
        uses: actions/configure-pages@v5

      # Documentation with Latex support
      # TODO(template) if Latex is not needed
      # just remove katex-header.html at the root and RUSTDOCFLAGS here
      # TODO(template) update the crate name
      - name: Build documentation
        run: RUSTDOCFLAGS="--html-in-header katex-header.html" cargo doc --no-deps -p template_crate

      - name: Remove lock file
        run: rm target/doc/.lock

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: target/doc

  publish-docs:
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    timeout-minutes: 5
    needs: docs
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4