From 85444f65f23d352da6d4c343e054706ed49e79d3 Mon Sep 17 00:00:00 2001 From: Sam Erde <20478745+SamErde@users.noreply.github.com> Date: Mon, 11 May 2026 05:14:37 -0400 Subject: [PATCH 1/2] Generate command docs before website build Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/build-website.yaml | 80 +++++++++++++++++++++++++++- 1 file changed, 78 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build-website.yaml b/.github/workflows/build-website.yaml index ebd43d1ec..14a32a100 100644 --- a/.github/workflows/build-website.yaml +++ b/.github/workflows/build-website.yaml @@ -1,6 +1,6 @@ # Validates that the Docusaurus website builds successfully. -# Runs on PRs that modify website files, and can also be called from other -# workflows or triggered manually. +# Runs on PRs that modify website files or docs source files, and can also be +# called from other workflows or triggered manually. name: "\U0001F3D7️ Build Website" on: @@ -20,6 +20,9 @@ on: pull_request: branches: ["main"] paths: + - "build/Update-CommandReference.ps1" + - "powershell/**" + - "tests/**" - "website/**" - ".github/workflows/build-website.yaml" @@ -28,17 +31,90 @@ concurrency: cancel-in-progress: ${{ github.event_name == 'pull_request' }} permissions: + actions: read contents: read jobs: + generate-command-reference: + name: "Generate command reference" + runs-on: windows-latest + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Generate command reference + shell: pwsh + run: ./build/Update-CommandReference.ps1 + + - name: Package generated command reference + shell: pwsh + run: | + $ProgressPreference = "SilentlyContinue" + $artifactRoot = Join-Path $env:GITHUB_WORKSPACE "generated-command-reference" + $docsRoot = Join-Path $artifactRoot "website/docs" + New-Item -ItemType Directory -Path $docsRoot -Force | Out-Null + + $sourceCommands = Join-Path $env:GITHUB_WORKSPACE "website/docs/commands" + if (-not (Test-Path $sourceCommands)) { + throw "Command reference docs were not generated at $sourceCommands." + } + + Copy-Item -Path $sourceCommands -Destination $docsRoot -Recurse -Force + + $versionedDocsRoot = Join-Path $env:GITHUB_WORKSPACE "website/versioned_docs" + if (Test-Path $versionedDocsRoot) { + foreach ($versionFolder in Get-ChildItem $versionedDocsRoot -Directory) { + $sourceVersionCommands = Join-Path $versionFolder.FullName "commands" + if (Test-Path $sourceVersionCommands) { + $targetVersionRoot = Join-Path $artifactRoot "website/versioned_docs/$($versionFolder.Name)" + New-Item -ItemType Directory -Path $targetVersionRoot -Force | Out-Null + Copy-Item -Path $sourceVersionCommands -Destination $targetVersionRoot -Recurse -Force + } + } + } + + Compress-Archive -Path (Join-Path $artifactRoot "*") -DestinationPath command-reference-docs.zip -Force + + - name: Upload generated command reference + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: generated-command-reference + path: command-reference-docs.zip + if-no-files-found: error + build: name: "Build Docusaurus website \U0001F3D7️" + needs: generate-command-reference runs-on: ubuntu-latest steps: - name: ⬇️ Checkout repository uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Download generated command reference + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: generated-command-reference + path: ${{ runner.temp }}/command-reference + + - name: Apply generated command reference + shell: pwsh + run: | + $ProgressPreference = "SilentlyContinue" + Remove-Item -Path ./website/docs/commands -Recurse -Force -ErrorAction SilentlyContinue + + $versionedDocsRoot = "./website/versioned_docs" + if (Test-Path $versionedDocsRoot) { + foreach ($versionFolder in Get-ChildItem $versionedDocsRoot -Directory) { + Remove-Item -Path (Join-Path $versionFolder.FullName "commands") -Recurse -Force -ErrorAction SilentlyContinue + } + } + + Expand-Archive -Path "${{ runner.temp }}/command-reference/command-reference-docs.zip" -DestinationPath . -Force + - name: ⚙️ Set up Node.js ${{ inputs.node_version || '24.x' }} uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 with: From af035a7b535fbc5a4d7d39d2b1832fcd043fcd67 Mon Sep 17 00:00:00 2001 From: Sam Erde <20478745+SamErde@users.noreply.github.com> Date: Mon, 11 May 2026 05:23:13 -0400 Subject: [PATCH 2/2] Address website docs workflow review Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/build-website.yaml | 45 ++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/.github/workflows/build-website.yaml b/.github/workflows/build-website.yaml index 14a32a100..1a338cd6d 100644 --- a/.github/workflows/build-website.yaml +++ b/.github/workflows/build-website.yaml @@ -33,10 +33,38 @@ concurrency: permissions: actions: read contents: read + pull-requests: read jobs: + detect-command-reference-changes: + name: "Detect command reference changes" + runs-on: ubuntu-latest + outputs: + generate: ${{ github.event_name != 'pull_request' || steps.filter.outputs.command_reference == 'true' }} + permissions: + contents: read + pull-requests: read + + steps: + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Check command reference inputs + if: github.event_name == 'pull_request' + id: filter + uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1 + with: + filters: | + command_reference: + - "build/Update-CommandReference.ps1" + - "powershell/**" + - "tests/**" + - ".github/workflows/build-website.yaml" + generate-command-reference: name: "Generate command reference" + needs: detect-command-reference-changes + if: needs.detect-command-reference-changes.outputs.generate == 'true' runs-on: windows-latest permissions: contents: read @@ -54,7 +82,7 @@ jobs: run: | $ProgressPreference = "SilentlyContinue" $artifactRoot = Join-Path $env:GITHUB_WORKSPACE "generated-command-reference" - $docsRoot = Join-Path $artifactRoot "website/docs" + $docsRoot = Join-Path $artifactRoot "docs" New-Item -ItemType Directory -Path $docsRoot -Force | Out-Null $sourceCommands = Join-Path $env:GITHUB_WORKSPACE "website/docs/commands" @@ -69,7 +97,7 @@ jobs: foreach ($versionFolder in Get-ChildItem $versionedDocsRoot -Directory) { $sourceVersionCommands = Join-Path $versionFolder.FullName "commands" if (Test-Path $sourceVersionCommands) { - $targetVersionRoot = Join-Path $artifactRoot "website/versioned_docs/$($versionFolder.Name)" + $targetVersionRoot = Join-Path $artifactRoot "versioned_docs/$($versionFolder.Name)" New-Item -ItemType Directory -Path $targetVersionRoot -Force | Out-Null Copy-Item -Path $sourceVersionCommands -Destination $targetVersionRoot -Recurse -Force } @@ -87,7 +115,8 @@ jobs: build: name: "Build Docusaurus website \U0001F3D7️" - needs: generate-command-reference + needs: [detect-command-reference-changes, generate-command-reference] + if: always() && needs.detect-command-reference-changes.result == 'success' && (needs.generate-command-reference.result == 'success' || needs.generate-command-reference.result == 'skipped') runs-on: ubuntu-latest steps: @@ -95,25 +124,29 @@ jobs: uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - name: Download generated command reference + if: needs.detect-command-reference-changes.outputs.generate == 'true' uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: name: generated-command-reference path: ${{ runner.temp }}/command-reference - name: Apply generated command reference + if: needs.detect-command-reference-changes.outputs.generate == 'true' shell: pwsh + env: + WEBSITE_WORKING_DIRECTORY: ${{ inputs.working_directory || 'website' }} run: | $ProgressPreference = "SilentlyContinue" - Remove-Item -Path ./website/docs/commands -Recurse -Force -ErrorAction SilentlyContinue + Remove-Item -Path (Join-Path $env:WEBSITE_WORKING_DIRECTORY "docs/commands") -Recurse -Force -ErrorAction SilentlyContinue - $versionedDocsRoot = "./website/versioned_docs" + $versionedDocsRoot = Join-Path $env:WEBSITE_WORKING_DIRECTORY "versioned_docs" if (Test-Path $versionedDocsRoot) { foreach ($versionFolder in Get-ChildItem $versionedDocsRoot -Directory) { Remove-Item -Path (Join-Path $versionFolder.FullName "commands") -Recurse -Force -ErrorAction SilentlyContinue } } - Expand-Archive -Path "${{ runner.temp }}/command-reference/command-reference-docs.zip" -DestinationPath . -Force + Expand-Archive -Path "${{ runner.temp }}/command-reference/command-reference-docs.zip" -DestinationPath $env:WEBSITE_WORKING_DIRECTORY -Force - name: ⚙️ Set up Node.js ${{ inputs.node_version || '24.x' }} uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0