learn.microsoft.com docs onboarding engsys #6818
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation automation infrastructure for the C++ SDK to support automated generation of docs.microsoft.com (Docs.MS) content. The changes enable automatic updates to documentation metadata, table of contents, and package onboarding configurations.
Key changes:
- Adds PowerShell scripts for Docs.MS table of contents generation and package onboarding
- Integrates documentation publishing into the release pipeline
- Configures documentation repository sync in the docindex pipeline
Reviewed Changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| sdk/template/azure-template/CHANGELOG.md | Adds "Other Changes" section header in changelog |
| eng/scripts/docs/Docs-ToC.ps1 | New script with functions for generating Docs.MS table of contents for C++ packages |
| eng/scripts/docs/Docs-Onboarding.ps1 | New script with functions for managing C++ package onboarding to Docs.MS |
| eng/scripts/Language-Settings.ps1 | Adds documentation-related variables and the Get-cpp-DocsMsMetadataForPackage function |
| eng/pipelines/templates/stages/archetype-cpp-release.yml | Adds new PublishDocsMs job to release pipeline |
| eng/pipelines/docindex.yml | Adds UpdateDocsMsBuildConfig job to update documentation configuration |
| .vscode/cspell.json | Adds custom dictionary entries for documentation-related terms |
| .gitignore | Excludes docs directory but includes eng/scripts/docs |
| # If there is a metadata json for the package use the DocsMsReadmeName from | ||
| # the metadata function | ||
| if ($packageMetadata.PSObject.Members.Name -contains "FileMetadata") { | ||
| $readmeMetadata = &$GetDocsMsMetadataForPackageFn -PackageInfo $packageMetadata.FileMetadata |
There was a problem hiding this comment.
The variable $GetDocsMsMetadataForPackageFn is used but not defined in this script. This variable should be available when common.ps1 is sourced. However, since Docs-ToC.ps1 is sourced directly in Language-Settings.ps1 (line 9) before common.ps1 is loaded, this variable will be undefined when the script is first parsed. Consider moving the sourcing of Docs-ToC.ps1 to after the common scripts are loaded, or ensure this script is only called after the common environment is initialized.
| # $GetDocsMsTocDataFn = "Get-${Language}-DocsMsTocData" | ||
| function Get-cpp-DocsMsTocData($packageMetadata, $docRepoLocation) { | ||
| $packageLevelReadmeName = GetPackageReadmeName -packageMetadata $packageMetadata | ||
| $packageTocHeader = GetDocsTocDisplayName $packageMetadata |
There was a problem hiding this comment.
The function GetDocsTocDisplayName is called but not defined in this script. This function is defined in eng/common/scripts/Helpers/Package-Helpers.ps1, which should be available through common.ps1. However, similar to Comment 1, this dependency may not be satisfied when this script is sourced early in Language-Settings.ps1. Ensure proper sourcing order or add explicit dependency documentation.
| } | ||
|
|
||
| # $GetRepositoryLinkFn = "Get-${Language}-RepositoryLink" | ||
| function Get-cpp-RepositoryLink($packageInfo) { |
There was a problem hiding this comment.
The variable $PackageRepositoryUri is used but not defined in this script. While it is defined in Language-Settings.ps1 (line 7), the sourcing order in Language-Settings.ps1 loads Docs-ToC.ps1 (line 9) before the variable is defined (line 7 comes before line 9), so this should work. However, this creates a fragile dependency where the order of declarations in the parent script matters. Consider explicitly passing this as a parameter or documenting this dependency.
| function Get-cpp-RepositoryLink($packageInfo) { | |
| function Get-cpp-RepositoryLink($packageInfo, $PackageRepositoryUri) { |
|
|
||
| - task: AzureCLI@2 | ||
| displayName: Queue Docs CI build | ||
| condition: and(succeeded(), or(eq(variables['Build.Reason'], 'Schedule'), eq(${{ parameters.StartMainSDKCIRun }}, true))) |
There was a problem hiding this comment.
[nitpick] The parameter name in the display text uses 'SDK CI' but the condition references it as 'StartMainSDKCIRun'. While this is consistent, the display name says 'Kick off the main SDK CI docs run' which could be clearer. Consider updating the display name to 'Start Main SDK CI Run' for consistency with the parameter name.
| $GithubUri = "https://github.com/Azure/azure-sdk-for-cpp" | ||
| $PackageRepositoryUri = "https://github.com/microsoft/vcpkg/tree/master/ports" | ||
|
|
||
| . "$PSScriptRoot/docs/Docs-ToC.ps1" |
There was a problem hiding this comment.
Sourcing Docs-ToC.ps1 at this location (line 9) occurs before the common scripts that define required variables like $GetDocsMsMetadataForPackageFn are loaded. While PowerShell allows this because function bodies are evaluated at call time, not parse time, this creates a fragile dependency order. Consider moving this line to after function definitions but before they are used, or add a comment explaining this dependency.
Partial: #6642
Depends on eng/common change: #6642