1 <#
2 .SYNOPSIS
3 Updates package README.md for publishing to docs.microsoft.com
4
5 .DESCRIPTION
6 Given a PackageInfo .json file, format the package README.md file with metadata
7 and 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
17 List of locations of the artifact information .json file. This is usually stored
18 in build artifacts under packages/PackageInfo/<package-name>.json. Can also be
19 a single item.
20
21 .PARAMETER DocRepoLocation
22 Location of the root of the docs.microsoft.com reference doc location. Further
23 path information is provided by $GetDocsMsMetadataForPackageFn
24
25 .PARAMETER Language
26 Programming language to supply to metadata
27
28 .PARAMETER RepoId
29 GitHub repository ID of the SDK. Typically of the form: 'Azure/azure-sdk-for-js'
30
31 #>
32
33 param(
34 [Parameter(Mandatory = $true)]
35 [array]$PackageInfoJsonLocations,
36
37 [Parameter(Mandatory = $true)]
38 [string]$DocRepoLocation,
39
40 [Parameter(Mandatory = $true)]
41 [string]$Language,
42
43 [Parameter(Mandatory = $true)]
44 [string]$RepoId
45 )
46
47 . (Join-Path $PSScriptRoot common.ps1)
48
49 $releaseReplaceRegex = "(https://github.com/$RepoId/(?:blob|tree)/)(?:master|main)"
50 $TITLE_REGEX = "(\#\s+(?<filetitle>Azure .+? (?:client|plugin|shared) library for (?:JavaScript|Java|Python|\.NET|C)))"
51
GetAdjustedReadmeContent($ReadmeContent, $PackageInfo, $PackageMetadata)52 function GetAdjustedReadmeContent($ReadmeContent, $PackageInfo, $PackageMetadata) {
53 # The $PackageMetadata could be $null if there is no associated metadata entry
54 # based on how the metadata CSV is filtered
55 $service = $PackageInfo.ServiceDirectory.ToLower()
56 if ($PackageMetadata -and $PackageMetadata.ServiceName) {
57 # Normalize service name "Key Vault" -> "keyvault"
58 # TODO: Use taxonomy for service name -- https://github.com/Azure/azure-sdk-tools/issues/1442
59 # probably from metadata
60 $service = $PackageMetadata.ServiceName.ToLower().Replace(" ", "")
61 }
62
63 # Generate the release tag for use in link substitution
64 $tag = "$($PackageInfo.Name)_$($PackageInfo.Version)"
65 $date = Get-Date -Format "MM/dd/yyyy"
66
67
68 $foundTitle = ""
69 if ($ReadmeContent -match $TITLE_REGEX) {
70 $ReadmeContent = $ReadmeContent -replace $TITLE_REGEX, "`${0} - Version $($PackageInfo.Version) `n"
71 $foundTitle = $matches["filetitle"]
72 }
73
74 # If this is not a daily dev package, perform link replacement
75 if (!$packageInfo.DevVersion) {
76 $replacementPattern = "`${1}$tag"
77 $ReadmeContent = $ReadmeContent -replace $releaseReplaceRegex, $replacementPattern
78 }
79
80 $header = @"
81 ---
82 title: $foundTitle
83 keywords: Azure, $Language, SDK, API, $($PackageInfo.Name), $service
84 author: maggiepint
85 ms.author: magpint
86 ms.date: $date
87 ms.topic: reference
88 ms.prod: azure
89 ms.technology: azure
90 ms.devlang: $Language
91 ms.service: $service
92 ---
93
94 "@
95
96 return "$header`n$ReadmeContent"
97 }
98
UpdateDocsMsMetadataForPackage($packageInfoJsonLocation)99 function UpdateDocsMsMetadataForPackage($packageInfoJsonLocation) {
100 $packageInfoJson = Get-Content $packageInfoJsonLocation -Raw
101 $packageInfo = ConvertFrom-Json $packageInfoJson
102
103 $originalVersion = [AzureEngSemanticVersion]::ParseVersionString($packageInfo.Version)
104 if ($packageInfo.DevVersion) {
105 # If the package is of a dev version there may be language-specific needs to
106 # specify the appropriate version. For example, in the case of JS, the dev
107 # version is always 'dev' when interacting with NPM.
108 if ($GetDocsMsDevLanguageSpecificPackageInfoFn -and (Test-Path "Function:$GetDocsMsDevLanguageSpecificPackageInfoFn")) {
109 $packageInfo = &$GetDocsMsDevLanguageSpecificPackageInfoFn $packageInfo
110 } else {
111 # Default: use the dev version from package info as the version for
112 # downstream processes
113 $packageInfo.Version = $packageInfo.DevVersion
114 }
115 }
116
117 $packageMetadataArray = (Get-CSVMetadata).Where({ $_.Package -eq $packageInfo.Name -and $_.GroupId -eq $packageInfo.Group -and $_.Hide -ne 'true' -and $_.New -eq 'true' })
118 if ($packageMetadataArray.Count -eq 0) {
119 LogWarning "Could not retrieve metadata for $($packageInfo.Name) from metadata CSV. Using best effort defaults."
120 $packageMetadata = $null
121 } elseif ($packageMetadataArray.Count -gt 1) {
122 LogWarning "Multiple metadata entries for $($packageInfo.Name) in metadata CSV. Using first entry."
123 $packageMetadata = $packageMetadataArray[0]
124 } else {
125 $packageMetadata = $packageMetadataArray[0]
126 }
127
128 $readmeContent = Get-Content $packageInfo.ReadMePath -Raw
129 $outputReadmeContent = ""
130 if ($readmeContent) {
131 $outputReadmeContent = GetAdjustedReadmeContent $readmeContent $packageInfo $packageMetadata
132 }
133
134 $docsMsMetadata = &$GetDocsMsMetadataForPackageFn $packageInfo
135 $readMePath = $docsMsMetadata.LatestReadMeLocation
136 if ($originalVersion.IsPrerelease) {
137 $readMePath = $docsMsMetadata.PreviewReadMeLocation
138 }
139
140 $suffix = $docsMsMetadata.Suffix
141 $readMeName = "$($docsMsMetadata.DocsMsReadMeName.ToLower())-readme${suffix}.md"
142
143 $readmeLocation = Join-Path $DocRepoLocation $readMePath $readMeName
144
145 Set-Content -Path $readmeLocation -Value $outputReadmeContent
146
147 # Copy package info file to the docs repo
148 $metadataMoniker = 'latest'
149 if ($originalVersion.IsPrerelease) {
150 $metadataMoniker = 'preview'
151 }
152 $packageMetadataName = Split-Path $packageInfoJsonLocation -Leaf
153 $packageInfoLocation = Join-Path $DocRepoLocation "metadata/$metadataMoniker"
154 $packageInfoJson = ConvertTo-Json $packageInfo
155 New-Item -ItemType Directory -Path $packageInfoLocation -Force
156 Set-Content `
157 -Path $packageInfoLocation/$packageMetadataName `
158 -Value $packageInfoJson
159 }
160
161 foreach ($packageInfo in $PackageInfoJsonLocations) {
162 Write-Host "Updating metadata for package: $packageInfo"
163 UpdateDocsMsMetadataForPackage $packageInfo
164 }
165