Split doc generation pipeline into parallel v1.0 and beta stages

azure-pipelines/common-templates/generate-docs-steps.yml

@@ -0,0 +1,165 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+#
+# Reusable steps that generate the Microsoft Graph PowerShell reference docs for a
+# single SDK profile (v1.0 or beta), commit the result to a dedicated branch and
+# open a pull request for that profile. Consumed by the parallel stages in
+# powershell-docs.yml so that v1.0 and beta each produce an independent PR.
+
+parameters:
+  - name: GraphProfileFilter
+    type: string
+    values:
+      - v1.0
+      - beta
+  - name: BranchPrefix
+    type: string
+  - name: PrTitle
+    type: string
+  - name: PrBody
+    type: string
+    default: "This pull request was automatically created by Azure Pipelines. **Important** Check for unexpected deletions or changes in this PR."
+
+steps:
+  - template: ../update-template.yml
+  - task: PowerShell@2
+    name: "ComputeBranch"
+    displayName: 'Compute Branch Name'
+    inputs:
+      targetType: 'inline'
+      script: |
+        git submodule update --init --recursive
+        $branch = "{0}_{1}" -f "${{ parameters.BranchPrefix }}", (Get-Date -Format yyyyMMddHHmm)
+        Write-Host "Compute branch: $branch"
+        Write-Host "##vso[task.setvariable variable=WeeklyReferenceDocsBranch;isOutput=true]$branch"
+  - task: Bash@3
+    displayName: "Create weekly refresh branch"
+    inputs:
+      targetType: inline
+      script: |
+        git status
+        git branch $(ComputeBranch.WeeklyReferenceDocsBranch)
+        git checkout $(ComputeBranch.WeeklyReferenceDocsBranch)
+        git status
+  - task: PowerShell@2
+    displayName: 'Create missing external docs folder'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/CreateExternalDocsFolder.ps1
+  - task: PowerShell@2
+    displayName: 'Generate markdown files from PowerShell help files'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/GenerateMarkDown.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Escape disallowed html tags'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/EscapeDisallowedHtmlTags.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Update metadata header'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/MsSubserviceUpdate.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Generate permissions table'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/GeneratePermissionsTable.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Update Links'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/UpdateLinks.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+      errorActionPreference: 'stop'
+  - task: PowerShell@2
+    displayName: 'Repair Examples and Descriptions and Title'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/RepairExamplesDescriptionsAndTitle.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Remove boiler plate code'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/RemoveBoilerPlateCode.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Remove invalid fullstops'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/RemoveInvalidFullStops.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Generate missing docs for aliased cmdlets'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/GenerateAliasedDocs.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Correct related links section'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/CorrectRelatedLinks-AllFiles.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: AzureKeyVault@2
+    displayName: "Azure Key Vault: Get GitHub App secrets"
+    inputs:
+      azureSubscription: "Federated AKV Managed Identity Connection"
+      KeyVaultName: akv-prod-eastus
+      SecretsFilter: "microsoft-graph-devx-bot-appid,microsoft-graph-devx-bot-privatekey"
+  - task: PowerShell@2
+    displayName: Pushing to github
+    env:
+      GhAppId: $(microsoft-graph-devx-bot-appid)
+      GhAppKey: $(microsoft-graph-devx-bot-privatekey)
+    inputs:
+      targetType: inline
+      pwsh: true
+      script: |
+        git config --global user.email "GraphTooling@service.microsoft.com"
+        git config --global user.name "Microsoft Graph DevX Tooling"
+        git config --system core.longpaths true
+        # The microsoft-graph-devx-bot GitHub App must have contents:write on this repo.
+        $token = & "$(Build.SourcesDirectory)/scripts/Generate-Github-Token.ps1" -AppClientId $env:GhAppId -AppPrivateKeyContents $env:GhAppKey -Repository "MicrosoftDocs/microsoftgraph-docs-powershell"
+        if ([string]::IsNullOrWhiteSpace($token)) { throw "Failed to generate GitHub App installation token." }
+        # Mask the token so it is never surfaced in pipeline logs.
+        Write-Host "##vso[task.setsecret]$token"
+        git status
+        git add .
+        git commit -m "Updating reference docs"
+        git push --set-upstream "******github.com/MicrosoftDocs/microsoftgraph-docs-powershell.git" $(ComputeBranch.WeeklyReferenceDocsBranch)
+        git status
+  - template: create-pr.yml
+    parameters:
+      BaseBranch: "main"
+      TargetBranch: $(ComputeBranch.WeeklyReferenceDocsBranch)
+      Title: "${{ parameters.PrTitle }}"
+      Body: "${{ parameters.PrBody }}"

azure-pipelines/powershell-docs.yml

@@ -47,148 +47,39 @@ extends:
     customBuildTags:
     - ES365AIMigrationTooling
     stages:
-    - stage: stage
+    - stage: GenerateV1
+      dependsOn: []
       jobs:
-      - job: PowerShellDocsUpdate
+      - job: GenerateV1Docs
         timeoutInMinutes: ${{ parameters.PipelineTimeout }}
         templateContext:
           outputs:
           - output: pipelineArtifact
             displayName: 'Publish Examples to be reviewed as artifact'
             targetPath: missingexternaldocsurl
-            artifactName: 'MissingExternalDocs'
+            artifactName: 'MissingExternalDocs-v1.0'
             publishLocation: 'Container'
         steps:
-        - template: azure-pipelines/update-template.yml@self
-        - task : PowerShell@2
-          name: "ComputeBranch"
-          displayName: 'Compute Branch Name'
-          inputs:
-            targetType: 'inline'
-            script: |
-              git submodule update --init --recursive
-              $branch = "{0}_{1}" -f "WeeklyReferenceDocsUpdate", (Get-Date -Format yyyyMMddHHmm)
-              Write-Host "Compute branch: $branch"
-              Write-Host "##vso[task.setvariable variable=WeeklyReferenceDocsBranch;isOutput=true]$branch"
-        - task: Bash@3
-          displayName: "Create weekly refresh branch"
-          inputs:
-            targetType: inline
-            script: |
-              git status
-              git branch $(ComputeBranch.WeeklyReferenceDocsBranch)
-              git checkout $(ComputeBranch.WeeklyReferenceDocsBranch)
-              git status              
-        - task: PowerShell@2
-          displayName: 'Create missing external docs folder'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/CreateExternalDocsFolder.ps1
-
-        - task: PowerShell@2
-          displayName: 'Generate markdown files from PowerShell help files'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/GenerateMarkDown.ps1
-        - task: PowerShell@2
-          displayName: 'Escape disallowed html tags'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/EscapeDisallowedHtmlTags.ps1
-        - task: PowerShell@2
-          displayName: 'Update metadata header'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/MsSubserviceUpdate.ps1
-        - task: PowerShell@2
-          displayName: 'Generate permissions table'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/GeneratePermissionsTable.ps1
-        - task: PowerShell@2
-          displayName: 'Update Links'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/UpdateLinks.ps1
-            errorActionPreference: 'stop'
-        - task: PowerShell@2
-          displayName: 'Repair Examples and Descriptions and Title'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/RepairExamplesDescriptionsAndTitle.ps1
-        - task: PowerShell@2
-          displayName: 'Remove boiler plate code'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/RemoveBoilerPlateCode.ps1
-        - task: PowerShell@2
-          displayName: 'Remove invalid fullstops'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/RemoveInvalidFullStops.ps1
-        - task: PowerShell@2
-          displayName: 'Generate missing docs for aliased cmdlets'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/GenerateAliasedDocs.ps1
-        - task: PowerShell@2
-          displayName: 'Correct related links section'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/CorrectRelatedLinks-AllFiles.ps1
-        - task: AzureKeyVault@2
-          displayName: "Azure Key Vault: Get GitHub App secrets"
-          inputs:
-            azureSubscription: "Federated AKV Managed Identity Connection"
-            KeyVaultName: akv-prod-eastus
-            SecretsFilter: "microsoft-graph-devx-bot-appid,microsoft-graph-devx-bot-privatekey"
-        - task: PowerShell@2
-          displayName: Pushing to github
-          env:
-            GhAppId: $(microsoft-graph-devx-bot-appid)
-            GhAppKey: $(microsoft-graph-devx-bot-privatekey)
-          inputs:
-            targetType: inline
-            pwsh: true
-            script: |
-              git config --global user.email "GraphTooling@service.microsoft.com"
-              git config --global user.name "Microsoft Graph DevX Tooling"
-              git config --system core.longpaths true
-              # The microsoft-graph-devx-bot GitHub App must have contents:write on this repo.
-              $token = & "$(Build.SourcesDirectory)/scripts/Generate-Github-Token.ps1" -AppClientId $env:GhAppId -AppPrivateKeyContents $env:GhAppKey -Repository "MicrosoftDocs/microsoftgraph-docs-powershell"
-              if ([string]::IsNullOrWhiteSpace($token)) { throw "Failed to generate GitHub App installation token." }
-              # Mask the token so it is never surfaced in pipeline logs.
-              Write-Host "##vso[task.setsecret]$token"
-              git status
-              git add .
-              git commit -m "Updating reference docs"
-              git push --set-upstream "https://x-access-token:$token@github.com/MicrosoftDocs/microsoftgraph-docs-powershell.git" $(ComputeBranch.WeeklyReferenceDocsBranch)
-              git status
-        - template: azure-pipelines/common-templates/create-pr.yml@self
+        - template: azure-pipelines/common-templates/generate-docs-steps.yml@self
           parameters:
-            BaseBranch: "main"
-            TargetBranch: $(ComputeBranch.WeeklyReferenceDocsBranch)
-            Title: "Weekly PowerShell Microsoft Graph Reference Docs Refresh"
-            Body: "This pull request was automatically created by Azure Pipelines. **Important** Check for unexpected deletions or changes in this PR."
+            GraphProfileFilter: 'v1.0'
+            BranchPrefix: 'WeeklyReferenceDocsUpdate-V1'
+            PrTitle: 'Weekly PowerShell Microsoft Graph v1.0 Reference Docs Refresh'
+    - stage: GenerateBeta
+      dependsOn: []
+      jobs:
+      - job: GenerateBetaDocs
+        timeoutInMinutes: ${{ parameters.PipelineTimeout }}
+        templateContext:
+          outputs:
+          - output: pipelineArtifact
+            displayName: 'Publish Examples to be reviewed as artifact'
+            targetPath: missingexternaldocsurl
+            artifactName: 'MissingExternalDocs-beta'
+            publishLocation: 'Container'
+        steps:
+        - template: azure-pipelines/common-templates/generate-docs-steps.yml@self
+          parameters:
+            GraphProfileFilter: 'beta'
+            BranchPrefix: 'WeeklyReferenceDocsUpdate-Beta'
+            PrTitle: 'Weekly PowerShell Microsoft Graph beta Reference Docs Refresh'

scripts/CorrectRelatedLinks-AllFiles.ps1

@@ -19,6 +19,7 @@ param(
 
     [Parameter(Mandatory = $false)]
     [ValidateSet("v1.0", "beta", "both")]
+    [Alias("GraphProfileFilter")]
     [string]$GraphProfile = "both"
 )
 

scripts/EscapeDisallowedHtmlTags.ps1

@@ -2,7 +2,9 @@
 # Licensed under the MIT License.
 Param(
     $ModulesToGenerate = @(),
-    [string] $ModuleMappingConfigPath = (Join-Path $PSScriptRoot "../microsoftgraph/config/ModulesMapping.jsonc")
+    [string] $ModuleMappingConfigPath = (Join-Path $PSScriptRoot "../microsoftgraph/config/ModulesMapping.jsonc"),
+    [ValidateSet("v1.0", "beta", "both")]
+    [string] $GraphProfileFilter = "both"
 )
 function Get-GraphMapping {
     $graphMapping = @{}
@@ -18,15 +20,27 @@ function EscapeDisallowedHtmlTags {
 
     $ModulePrefix = "Microsoft.Graph"
     $GraphMapping = Get-GraphMapping 
-    $GraphMapping.Keys | ForEach-Object {
+    $profilesToProcess = if ($GraphProfileFilter -eq 'both') { $GraphMapping.Keys } else { @($GraphProfileFilter) }
+    $profilesToProcess | ForEach-Object {
         $graphProfile = $_
         Get-FilesByProfile -GraphProfile $graphProfile -GraphProfilePath $GraphMapping[$graphProfile] -ModulePrefix $ModulePrefix -ModulesToGenerate $ModulesToGenerate 
     }
 
     git config --global user.email "GraphTooling@service.microsoft.com"
     git config --global user.name "Microsoft Graph DevX Tooling"
     git add .
-    git commit -m "Escaped disallowed html tags" 	
+
+    # Check for staged changes; commit only if any exist
+    $pending = git status --porcelain
+    if (-not [string]::IsNullOrWhiteSpace($pending)) {
+        git commit -m "Escaped disallowed html tags"
+        Write-Host "Committed escaping of disallowed html tags."
+    }
+    else {
+        Write-Host "Nothing to commit; skipping commit step."
+        # Ensure a clean exit code even if earlier native commands returned 1
+        $global:LASTEXITCODE = 0
+    }
 }
 function Get-FilesByProfile {
     Param(