docs.yml

# Builds the documentation site (guides plus API reference generated from the XML doc comments) and
# publishes it to GitHub Pages on every push to main.
name: Docs

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
        with:
          dotnet-version: |
            8.0.x
            10.0.x
      - name: Restore tools
        run: dotnet tool restore
      - name: Build site
        run: dotnet docfx docs/docfx.json --warningsAsErrors

      # The coverage badge in the README reads docs/_site/coverage.json through shields.io's endpoint
      # badge. Serving it from the docs site keeps the number honest (it comes from a real test run on
      # main) without a third-party coverage service or a stored token.
      - name: Test with coverage
        run: dotnet test -c Release --collect:"XPlat Code Coverage" --results-directory coverage
      - name: Write coverage badge data
        run: |
          python3 - <<'PY'
          import glob, json, xml.etree.ElementTree as ET
          rate = max(float(ET.parse(f).getroot().get("line-rate")) for f in glob.glob("coverage/**/coverage.cobertura.xml", recursive=True)) * 100
          color = "brightgreen" if rate >= 90 else "green" if rate >= 80 else "yellow" if rate >= 70 else "orange"
          json.dump({"schemaVersion": 1, "label": "coverage", "message": f"{rate:.1f}%", "color": color}, open("docs/_site/coverage.json", "w"))
          print(f"line coverage {rate:.1f}%")
          PY

      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: docs/_site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write      # publish the site
      id-token: write   # verify the deployment origin
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1