docs.yml

name: Docs
on:
  push:
  pull_request:
    branches:
    - reorganize

# 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

defaults:
  run:
    shell: pwsh

env:
  DOTNET_TELEMETRY_OPTOUT: true
  DOTNET_NOLOGO: true
  NUGET_PACKAGES: ${{github.workspace}}/artifacts/pkg
  RestoreLockedMode: true
  
  # We have to force the Roslyn version to be 4.14, because docfx ships that version, and if we target newer for the DocFX build,
  # our source generators won't load. This can be extracted from Directory.Packages.props in the docfx repo.
  RoslynVersion: 4.14.0

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
    - name: Configure git
      run: |
        git config --global core.autocrlf input

    - name: Checkout
      uses: actions/checkout@v4
      with:
        lfs: true
        submodules: recursive
        
    - name: Install .NET SDK
      uses: nike4613/install-dotnet@6625f6cf2b076b088eee77a005f5f226e89aa580
      with:
        global-json: global.json
        
    # NOTE: manual package caching
    - name: Cache restored NuGet packages
      uses: actions/cache@v4
      with:
        path: ${{ env.NUGET_PACKAGES }}
        key: ${{ runner.os }}-nuget-v2-${{ hashFiles('**/packages.lock.json') }}
        restore-keys: ${{ runner.os }}-nuget-setup-v2-${{ hashFiles('build/gen-test-matrix/packages.lock.json') }}
        
    - name: Restore
      run: dotnet restore -bl:restore.binlog -noAutoRsp -p:RestoreLockedMode=false -p:RoslynVersion=${{ env.RoslynVersion }}

    - name: Restore .NET tools
      run: dotnet tool restore

    - name: Build all projects # don't run any analyzers to speed up this build
      run: dotnet build --no-restore -c Release -noAutoRsp -bl:build.binlog -p:RunAnalyzers=false -p:RoslynVersion=${{ env.RoslynVersion }}

    - name: Build DocFX project
      run: dotnet docfx docfx/docfx.json

    - name: Upload binlogs
      uses: actions/upload-artifact@v4
      if: ${{ always() }}
      with:
        name: docs-binlogs
        path: '*.binlog'
        retention-days: 7
        
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      with:
        # Upload entire repository
        path: 'docfx/_site'
    
  publish-docs:
    needs: [build-docs]
    if: ${{ github.event_name == 'push' && github.ref_name == 'reorganize' }}
    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
    permissions:
      actions: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4