psdocs-mdtogit.yml

# Example: .github/workflows/arm-docs.yaml

name: Check Docs Generation
on:
  pull_request:
    types:
      - edited
      - opened
      - reopened
      - synchronize
    paths:
      - '**.bicep'

jobs:
  arm_docs:
    name: Check Docs Generation
    permissions:
      contents: read
    runs-on: ubuntu-latest
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0
        with:
          egress-policy: audit

      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Generate Docs
        run: |
          Write-Host "==> Starting Bicep build (parallel capable)"
          $bicepFiles = Get-ChildItem -Recurse -Path infra-as-code/bicep/ -Filter '*.bicep' -Exclude 'callModuleFromACR.example.bicep','orchHubSpoke.bicep'
          if ($PSVersionTable.PSVersion.Major -lt 7) {
            Write-Host "PowerShell version does not support -Parallel. Falling back to sequential builds."
            foreach ($f in $bicepFiles) {
              Write-Information "==> Attempting Bicep Build For File: $f" -InformationAction Continue
              $null = bicep build $f.FullName 2>&1 | Tee-Object -Variable buildOut
              if ($LASTEXITCODE -ne 0) { throw "Bicep build failed for $($f.FullName): `n$buildOut" }
            }
          }
          else {
            $throttle = if ($env:BICEP_BUILD_PARALLEL_LIMIT) { [int]$env:BICEP_BUILD_PARALLEL_LIMIT } else { 8 }
            Write-Host "Using parallel builds with ThrottleLimit=$throttle"
            $errors = [System.Collections.Concurrent.ConcurrentBag[string]]::new()
            $bicepFiles | ForEach-Object -Parallel {
              $file = $_.FullName
              $maxAttempts = 3
              $attempt = 0
              $success = $false
              while (-not $success -and $attempt -lt $maxAttempts) {
                $attempt++
                try {
                  Write-Information "==> [Parallel] Building (Attempt $attempt/$maxAttempts): $file" -InformationAction Continue
                  $out = bicep build $file 2>&1
                  if ($LASTEXITCODE -ne 0) {
                    if ($attempt -lt $maxAttempts) {
                      Write-Warning "Build failed for $file (attempt $attempt). Retrying..."
                      Start-Sleep -Seconds ([int][Math]::Pow(2, $attempt))
                    }
                    else {
                      $errMsg = "Bicep build failed after {0} attempts for {1}: `n{2}" -f $maxAttempts, $file, ($out -join "`n")
                      throw $errMsg
                    }
                  }
                  else {
                    $out | ForEach-Object { Write-Host $_ }
                    $success = $true
                  }
                }
                catch {
                  if ($attempt -ge $maxAttempts) {
                    [System.Console]::Error.WriteLine($_)
                    $errBag = $using:errors
                    $msg = "{0}: {1}" -f $file, $_
                    [void]$errBag.Add($msg)
                  }
                }
              }
            } -ThrottleLimit $throttle
            if ($errors.Count -gt 0) {
              Write-Host '--- Bicep build errors detected ---'
              $errors | ForEach-Object { Write-Host $_ }
              throw "One or more Bicep builds failed."
            }
          }

          Install-Module -Name 'PSDocs.Azure' -Repository PSGallery -force; Import-Module PSDocs.Azure -Force
          # Scan for Azure template file recursively in the infra-as-code/bicep/ directory and generate markdown in parallel
          Write-Host "==> Starting markdown generation (parallel capable)"
          $templates = Get-AzDocTemplateFile -Path infra-as-code/bicep/
          $mdThrottle = if ($env:MD_GEN_PARALLEL_LIMIT) { [int]$env:MD_GEN_PARALLEL_LIMIT } else { 8 }
          $mdErrors = [System.Collections.Concurrent.ConcurrentBag[string]]::new()
          if ($PSVersionTable.PSVersion.Major -lt 7) {
            Write-Host "PowerShell version does not support -Parallel for markdown generation. Falling back to sequential."
            foreach ($t in $templates) {
              try {
                $template = Get-Item -Path $t.TemplateFile
                $templateraw = Get-Content -Raw -Path $t.Templatefile
                $version = $template.Directory.Name
                $docNameWithoutExtension = [System.IO.Path]::GetFileNameWithoutExtension($template.Name)
                $jobj = ConvertFrom-Json -InputObject $templateraw
                $outputpathformds = $template.DirectoryName + '/generateddocs'
                New-Item -Path $outputpathformds -ItemType Directory -Force | Out-Null
                $convertedfullpath = $template.DirectoryName + "\\" + $template.Name
                $jobj | ConvertTo-Json -Depth 100 | Set-Content -Path $convertedfullpath
                $mdname = $docNameWithoutExtension + '.bicep'
                Invoke-PSDocument -Module PSDocs.Azure -OutputPath $outputpathformds -InputObject $template.FullName -InstanceName $mdname -Culture en-US
              }
              catch {
                Write-Host "[Markdown-Error] $($template.FullName): $_"
                $mdErrors.Add("$($template.FullName): $_")
              }
            }
          }
          else {
            Write-Host "Using parallel markdown generation with ThrottleLimit=$mdThrottle"
            $templates | ForEach-Object -Parallel {
              try {
                $template = Get-Item -Path $_.TemplateFile
                $templateraw = Get-Content -Raw -Path $_.Templatefile
                $version = $template.Directory.Name
                $docNameWithoutExtension = [System.IO.Path]::GetFileNameWithoutExtension($template.Name)
                $jobj = ConvertFrom-Json -InputObject $templateraw
                $outputpathformds = $template.DirectoryName + '/generateddocs'
                New-Item -Path $outputpathformds -ItemType Directory -Force | Out-Null
                $convertedfullpath = $template.DirectoryName + "\\" + $template.Name
                $jobj | ConvertTo-Json -Depth 100 | Set-Content -Path $convertedfullpath
                $mdname = $docNameWithoutExtension + '.bicep'
                Invoke-PSDocument -Module PSDocs.Azure -OutputPath $outputpathformds -InputObject $template.FullName -InstanceName $mdname -Culture en-US
              }
              catch {
                [System.Console]::Error.WriteLine($_)
                $mdErrBag = $using:mdErrors
                $msg = "{0}: {1}" -f $_.TemplateFile, $_
                [void]$mdErrBag.Add($msg)
              }
            } -ThrottleLimit $mdThrottle
          }
          if ($mdErrors.Count -gt 0) {
            Write-Host '--- Markdown generation errors detected ---'
            $mdErrors | ForEach-Object { Write-Host $_ }
            throw "One or more markdown generations failed."
          }

          Get-ChildItem -Recurse -Path infra-as-code/bicep/ -Filter '*.json' -Exclude 'bicepconfig.json','*.parameters.json','*.parameters.*.json','policy_*' | ForEach-Object {
            Write-Information "==> Removing generated JSON file $_ from Bicep Build" -InformationAction Continue
            Remove-Item -Path $_.FullName
          }
        shell: pwsh

      - name: Check git status
        run: |
          echo "==> Check git status..."
          git status

      - name: Fail if markdown docs changed
        shell: pwsh
        run: |
          Write-Host "==> Verifying no markdown (*.md) changes were produced by doc generation..."
          $mdChanges = git status --porcelain | Where-Object { $_ -match '\.md$' }
          if ($mdChanges) {
            Write-Host '::warning::Markdown documentation changes detected. These should be generated and committed locally.'
            Write-Host "Changed markdown files:";
            $mdChanges | ForEach-Object { Write-Host $_ }
            Write-Host ''
            Write-Host 'Unified diff (markdown changes):'
            # Extract just the file paths (status codes in first 3 chars of porcelain output)
            $mdFiles = $mdChanges | ForEach-Object { $_.Substring(3) }
            foreach ($f in $mdFiles) {
              Write-Host "---- Diff: $f ----"
              git --no-pager diff --unified=3 -- $f | Write-Host
            }
            Write-Host ''
            Write-Host 'To fix:'
            Write-Host '  1. Follow the manual generation steps in the contributing guide:'
            Write-Host '     https://github.com/Azure/ALZ-Bicep/wiki/Contributing#manually-generating-the-parameter-markdown-files'
            Write-Host '  2. Regenerate the parameter markdown files locally, as per instructions.'
            Write-Host '  3. Commit the updated .md files and push to this branch.'
            Write-Host ''
            Write-Host 'Failing the workflow to enforce up-to-date documentation.'
            exit 1
          }
          else {
            Write-Host 'No markdown documentation changes detected.'
          }