docs.yml

name: 📚 Docs

on:
  push:
    branches:
    - main
  workflow_dispatch:

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  publish-docs:
    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
    permissions:
      actions: read
      pages: write
      id-token: write
      contents: read
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-26.04
    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        fetch-depth: 0 # avoid shallow clone so nbgv can do its work.
    - name: ⚙ Install prerequisites
      run: ./init.ps1 -UpgradePrerequisites -NoNuGetCredProvider

    - run: dotnet docfx docfx/docfx.json
      name: 📚 Generate documentation
      env:
        DocFx: true # Workaround https://github.com/dotnet/docfx/issues/10808

    - name: Upload artifact
      uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
      with:
        path: docfx/_site
        # Artifacts from prior attempts remain visible on re-runs, so make the name unique per attempt
        # to avoid deploy-pages failing due to multiple artifacts with the same name.
        name: github-pages-${{ github.run_attempt }}

    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
      with:
        artifact_name: github-pages-${{ github.run_attempt }}