1<#
2.SYNOPSIS
3Updates package README.md for publishing to docs.microsoft.com
4
5.DESCRIPTION
6Given a PackageInfo .json file, format the package README.md file with metadata
7and other information needed to release reference docs:
8
9* Adjust README.md content to include metadata
10* Insert the package verison number in the README.md title
11* Copy file to the appropriate location in the documentation repository
12* Copy PackageInfo .json file to the metadata location in the reference docs
13 repository. This enables the Docs CI build to onboard packages which have not
14 shipped and for which there are no entries in the metadata CSV files.
15
16.PARAMETER PackageInfoJsonLocations
17List of locations of the artifact information .json file. This is usually stored
18in build artifacts under packages/PackageInfo/<package-name>.json. Can also be
19a single item.
20
21.PARAMETER DocRepoLocation
22Location of the root of the docs.microsoft.com reference doc location. Further
23path information is provided by $GetDocsMsMetadataForPackageFn
24
25.PARAMETER Language
26Programming language to supply to metadata
27
28.PARAMETER RepoId
29GitHub repository ID of the SDK. Typically of the form: 'Azure/azure-sdk-for-js'
30
31.PARAMETER DocValidationImageId
32The docker image id in format of '$containerRegistry/$imageName:$tag'
33e.g. azuresdkimages.azurecr.io/jsrefautocr:latest
34
35.PARAMETER TenantId
36The aad tenant id/object id.
37
38.PARAMETER ClientId
39The add client id/application id.
40
41.PARAMETER ClientSecret
42The client secret of add app.
43#>
44
45param(
46 [Parameter(Mandatory = $true)]
47 [array]$PackageInfoJsonLocations,
48
49 [Parameter(Mandatory = $true)]
50 [string]$DocRepoLocation,
51
52 [Parameter(Mandatory = $true)]
53 [string]$Language,
54
55 [Parameter(Mandatory = $true)]
56 [string]$RepoId,
57
58 [Parameter(Mandatory = $false)]
59 [string]$DocValidationImageId,
60
61 [Parameter(Mandatory = $false)]
62 [string]$PackageSourceOverride,
63
64 [Parameter(Mandatory = $false)]
65 [string]$TenantId,
66
67 [Parameter(Mandatory = $false)]
68 [string]$ClientId,
69
70 [Parameter(Mandatory = $false)]
71 [string]$ClientSecret
72)
73Set-StrictMode -Version 3
74. (Join-Path $PSScriptRoot common.ps1)
75. (Join-Path $PSScriptRoot Helpers Metadata-Helpers.ps1)
76
77$releaseReplaceRegex = "(https://github.com/$RepoId/(?:blob|tree)/)(?:master|main)"
78$TITLE_REGEX = "(\#\s+(?<filetitle>Azure .+? (?:client|plugin|shared) library for (?:JavaScript|Java|Python|\.NET|C)))"
79
80function GetAdjustedReadmeContent($ReadmeContent, $PackageInfo, $PackageMetadata) {
81 # The $PackageMetadata could be $null if there is no associated metadata entry
82 # based on how the metadata CSV is filtered
83 $service = $PackageInfo.ServiceDirectory.ToLower()
84 if ($PackageMetadata -and $PackageMetadata.MSDocService) {
85 # Use MSDocService in csv metadata to override the service directory
86 # TODO: Use taxonomy for service name -- https://github.com/Azure/azure-sdk-tools/issues/1442
87 $service = $PackageMetadata.MSDocService
88 }
89 Write-Host "The service of package: $service"
90 # Generate the release tag for use in link substitution
91 $tag = "$($PackageInfo.Name)_$($PackageInfo.Version)"
92 Write-Host "The tag of package: $tag"
93 $date = Get-Date -Format "MM/dd/yyyy"
94
95
96 $foundTitle = ""
97 if ($ReadmeContent -match $TITLE_REGEX) {
98 $ReadmeContent = $ReadmeContent -replace $TITLE_REGEX, "`${0} - Version $($PackageInfo.Version) `n"
99 $foundTitle = $matches["filetitle"]
100 }
101
102 # If this is not a daily dev package, perform link replacement
103 if (!$packageInfo.DevVersion) {
104 $replacementPattern = "`${1}$tag"
105 $ReadmeContent = $ReadmeContent -replace $releaseReplaceRegex, $replacementPattern
106 }
107
108 # Get the first code owners of the package.
109 Write-Host "Retrieve the code owner from $($PackageInfo.DirectoryPath)."
110 $author = GetPrimaryCodeOwner -TargetDirectory $PackageInfo.DirectoryPath
111 if (!$author) {
112 $author = "ramya-rao-a"
113 $msauthor = "ramyar"
114 }
115 else {
116 $msauthor = GetMsAliasFromGithub -TenantId $TenantId -ClientId $ClientId -ClientSecret $ClientSecret -GithubUser $author
117 }
118 # Default value
119 if (!$msauthor) {
120 $msauthor = $author
121 }
122 Write-Host "The author of package: $author"
123 Write-Host "The ms author of package: $msauthor"
124 $header = @"
125---
126title: $foundTitle
127keywords: Azure, $Language, SDK, API, $($PackageInfo.Name), $service
128author: $author
129ms.author: $msauthor
130ms.date: $date
131ms.topic: reference
132ms.devlang: $Language
133ms.service: $service
134---
135"@
136
137 $ReadmeContent = $ReadmeContent -replace "https://docs.microsoft.com(/en-us)?/?", "/"
138 return "$header`n$ReadmeContent"
139}
140
141function GetPackageInfoJson ($packageInfoJsonLocation) {
142 if (!(Test-Path $packageInfoJsonLocation)) {
143 LogWarning "Package metadata not found for $packageInfoJsonLocation"
144 return
145 }
146
147 $packageInfoJson = Get-Content $packageInfoJsonLocation -Raw
148 $packageInfo = ConvertFrom-Json $packageInfoJson
149 if ($packageInfo.DevVersion) {
150 # If the package is of a dev version there may be language-specific needs to
151 # specify the appropriate version. For example, in the case of JS, the dev
152 # version is always 'dev' when interacting with NPM.
153 if ($GetDocsMsDevLanguageSpecificPackageInfoFn -and (Test-Path "Function:$GetDocsMsDevLanguageSpecificPackageInfoFn")) {
154 $packageInfo = &$GetDocsMsDevLanguageSpecificPackageInfoFn $packageInfo
155 }
156 else {
157 # Default: use the dev version from package info as the version for
158 # downstream processes
159 $packageInfo.Version = $packageInfo.DevVersion
160 }
161 }
162 return $packageInfo
163}
164
165function UpdateDocsMsMetadataForPackage($packageInfoJsonLocation) {
166 $packageInfo = GetPackageInfoJson $packageInfoJsonLocation
167
168 $originalVersion = [AzureEngSemanticVersion]::ParseVersionString($packageInfo.Version)
169 $packageMetadataArray = (Get-CSVMetadata).Where({ $_.Package -eq $packageInfo.Name -and $_.Hide -ne 'true' -and $_.New -eq 'true' })
170 if ($packageInfo.Group) {
171 $packageMetadataArray = ($packageMetadataArray).Where({ $_.GroupId -eq $packageInfo.Group })
172 }
173 if ($packageMetadataArray.Count -eq 0) {
174 LogWarning "Could not retrieve metadata for $($packageInfo.Name) from metadata CSV. Using best effort defaults."
175 $packageMetadata = $null
176 }
177 elseif ($packageMetadataArray.Count -gt 1) {
178 LogWarning "Multiple metadata entries for $($packageInfo.Name) in metadata CSV. Using first entry."
179 $packageMetadata = $packageMetadataArray[0]
180 }
181 else {
182 $packageMetadata = $packageMetadataArray[0]
183 }
184
185 # Copy package info file to the docs repo
186 $docsMsMetadata = &$GetDocsMsMetadataForPackageFn $packageInfo
187 $readMePath = $docsMsMetadata.LatestReadMeLocation
188 $metadataMoniker = 'latest'
189 if ($originalVersion -and $originalVersion.IsPrerelease) {
190 $metadataMoniker = 'preview'
191 $readMePath = $docsMsMetadata.PreviewReadMeLocation
192 }
193 $packageMetadataName = Split-Path $packageInfoJsonLocation -Leaf
194 $packageInfoLocation = Join-Path $DocRepoLocation "metadata/$metadataMoniker"
195 $packageInfoJson = ConvertTo-Json $packageInfo
196 New-Item -ItemType Directory -Path $packageInfoLocation -Force
197 Set-Content `
198 -Path $packageInfoLocation/$packageMetadataName `
199 -Value $packageInfoJson
200
201 # Update Readme Content
202 if (!$packageInfo.ReadMePath -or !(Test-Path $packageInfo.ReadMePath)) {
203 Write-Warning "$($packageInfo.Name) does not have Readme file. Skipping update readme."
204 return
205 }
206
207 $readmeContent = Get-Content $packageInfo.ReadMePath -Raw
208 $outputReadmeContent = ""
209 if ($readmeContent) {
210 $outputReadmeContent = GetAdjustedReadmeContent $readmeContent $packageInfo $packageMetadata
211 }
212
213 $suffix = $docsMsMetadata.Suffix
214 $readMeName = "$($docsMsMetadata.DocsMsReadMeName.ToLower())-readme${suffix}.md"
215
216 $readmeLocation = Join-Path $DocRepoLocation $readMePath $readMeName
217
218 Set-Content -Path $readmeLocation -Value $outputReadmeContent
219}
220
221# For daily update and release, validate DocsMS publishing using the language-specific validation function
222if ($ValidateDocsMsPackagesFn -and (Test-Path "Function:$ValidateDocsMsPackagesFn")) {
223 Write-Host "Validating the packages..."
224
225 $packageInfos = @($PackageInfoJsonLocations | ForEach-Object { GetPackageInfoJson $_ })
226
227 &$ValidateDocsMsPackagesFn -PackageInfos $packageInfos -PackageSourceOverride $PackageSourceOverride -DocValidationImageId $DocValidationImageId -DocRepoLocation $DocRepoLocation
228}
229
230foreach ($packageInfoLocation in $PackageInfoJsonLocations) {
231 Write-Host "Updating metadata for package: $packageInfoLocation"
232 # Convert package metadata json file to metadata json property.
233 UpdateDocsMsMetadataForPackage $packageInfoLocation
234}
View as plain text