docs.yml

# Builds the docs site from the guides in docs/, the root README, the package READMEs, the changelog and the API of
# the run-time packages, and publishes it to GitHub Pages from main (#115, design/adr/0116-the-docs-site-is-docfx-built-from-main.md):
#
#   https://caffeinatedcoder.github.io/CodoMetis.TypeKit/
#
# Only main is published, because main is the released state: topics merge into release/<version>, which merges into
# main when it is tagged, so the site always describes the version `dotnet add package` installs. A release branch
# is never published. A second line under its own path (/2.x/, /3.x/) waits until two lines are supported at once;
# CONTRIBUTING.md ("The docs site") says how one would be added.
#
# A pull request into main or a release branch that touches what a page is built from builds the site and publishes
# nothing. DocFX runs with warnings as errors, so a link to a missing page, a missing heading or a missing file of the
# repository fails the pull request rather than the deployment.
#
# The pages are the Markdown files as they are: nothing copies or edits them, so ReadmeSampleTests and
# OracleCatalogueTests hold the text readers see. A link to a file of the repository that is not a page (design/,
# CONTRIBUTING.md) becomes a GitHub address at the built commit in site/template, at build time.
#
# Pages is configured to deploy from GitHub Actions (Settings > Pages > Source), the one setting no workflow can make.
#
# Actions are pinned to commit SHAs, as in dotnet.yml.

name: Docs

# Everything a page is built from: the Markdown, the XML docs in src/, the site's config, and the SDK and tool pins.
# Keep the two lists the same.
on:
  push:
    branches: [ "main" ]
    paths:
      - "*.md"
      - "LICENSE"
      - "docs/**"
      - "design/**"
      - "src/**"
      - "site/**"
      - "global.json"
      - "Directory.Build.props"
      - "Directory.Packages.props"
      - ".config/dotnet-tools.json"
      - ".github/workflows/docs.yml"
  pull_request:
    branches: [ "main", "release/**" ]
    paths:
      - "*.md"
      - "LICENSE"
      - "docs/**"
      - "design/**"
      - "src/**"
      - "site/**"
      - "global.json"
      - "Directory.Build.props"
      - "Directory.Packages.props"
      - ".config/dotnet-tools.json"
      - ".github/workflows/docs.yml"
  workflow_dispatch:

permissions:
  contents: read

defaults:
  run:
    shell: bash

# A pull request's run is superseded by its next push. Publishing runs queue instead, so a deployment is never
# cancelled halfway and the last one to finish publishes the latest main.
concurrency:
  group: ${{ github.event_name == 'pull_request' && format('docs-{0}', github.ref) || 'docs-publish' }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  DOTNET_NOLOGO: true
  DOTNET_CLI_TELEMETRY_OPTOUT: true
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true

jobs:
  build:
    name: Build the site
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          persist-credentials: false

      - name: Setup .NET
        uses: actions/setup-dotnet@26b0ec14cb23fa6904739307f278c14f94c95bf1 # v5.4.0
        with:
          global-json-file: global.json

      # The API pages are read from published assemblies, which carry the XML docs and every dependency DocFX needs
      # to resolve a signature. The packages are the ones site/docfx.json names, so the two cannot disagree.
      - name: Publish the run-time packages
        run: |
          for assembly in $(jq -r '.metadata[].src[].files[]' site/docfx.json); do
            dotnet publish "src/${assembly%.dll}" -c Release -o site/obj/pub
          done

      - name: Build the site, warnings as errors
        run: |
          dotnet tool restore
          dotnet docfx site/docfx.json --warningsAsErrors --metadata _commit="$GITHUB_SHA"

      # The members of C# 14 extension blocks are listed as extension methods, on their static class and on the type
      # they extend: measured with DocFX 2.81.0 (decision 116). A DocFX that stops listing them fails here, not on
      # a reader who finds Option<T>'s page without its combinators.
      - name: The extension-block members are listed
        run: |
          grep -qF '  - CodoMetis.TypeKit.Option`1.CodoMetis.TypeKit.Option.Select``2(' site/obj/api/CodoMetis.TypeKit.Option-1.yml
          grep -qF '  - CodoMetis.TypeKit.Result`2.CodoMetis.TypeKit.Result.Select``3(' site/obj/api/CodoMetis.TypeKit.Result-2.yml

      # The files a link of a page names to be checked, which the site links on GitHub instead (site/template).
      - name: Leave the repository's own files out
        run: rm -rf site/obj/_site/_repository

      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
        with:
          path: site/obj/_site

  publish:
    name: Publish
    needs: build
    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}

    steps:
      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

      - id: deploy
        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1