|
| 1 | +<# |
| 2 | +.SYNOPSIS |
| 3 | +The script is to generate service level readme if it is missing. |
| 4 | +For exist ones, we do 2 things here: |
| 5 | +1. Generate the client but not import to the existing service level readme. |
| 6 | +2. Update the metadata of service level readme |
| 7 | +
|
| 8 | +.DESCRIPTION |
| 9 | +Given a doc repo location, and the credential for fetching the ms.author. |
| 10 | +Generate missing service level readme and updating metadata of the existing ones. |
| 11 | +
|
| 12 | +.PARAMETER DocRepoLocation |
| 13 | +Location of the documentation repo. This repo may be sparsely checked out |
| 14 | +depending on the requirements for the domain |
| 15 | +
|
| 16 | +.PARAMETER TenantId |
| 17 | +The aad tenant id/object id for ms.author. |
| 18 | +
|
| 19 | +.PARAMETER ClientId |
| 20 | +The add client id/application id for ms.author. |
| 21 | +
|
| 22 | +.PARAMETER ClientSecret |
| 23 | +The client secret of add app for ms.author. |
| 24 | +#> |
| 25 | + |
| 26 | +param( |
| 27 | + [Parameter(Mandatory = $true)] |
| 28 | + [string] $DocRepoLocation, |
| 29 | + |
| 30 | + [Parameter(Mandatory = $false)] |
| 31 | + [string]$TenantId, |
| 32 | + |
| 33 | + [Parameter(Mandatory = $false)] |
| 34 | + [string]$ClientId, |
| 35 | + |
| 36 | + [Parameter(Mandatory = $false)] |
| 37 | + [string]$ClientSecret |
| 38 | +) |
| 39 | +. $PSScriptRoot/common.ps1 |
| 40 | +. $PSScriptRoot/Helpers/Metadata-Helpers.ps1 |
| 41 | +. $PSScriptRoot/Helpers/Package-Helpers.ps1 |
| 42 | + |
| 43 | +Set-StrictMode -Version 3 |
| 44 | + |
| 45 | +function create-metadata-table($readmeFolder, $readmeName, $moniker, $msService, $clientTableLink, $mgmtTableLink, $serviceName) |
| 46 | +{ |
| 47 | + $readmePath = Join-Path $readmeFolder -ChildPath $readmeName |
| 48 | + $content = "" |
| 49 | + if (Test-Path (Join-Path $readmeFolder -ChildPath $clientTableLink)) { |
| 50 | + $content = "## Client packages - $moniker`r`n" |
| 51 | + $content += "[!INCLUDE [client-packages]($clientTableLink)]`r`n" |
| 52 | + } |
| 53 | + if (Test-Path (Join-Path $readmeFolder -ChildPath $mgmtTableLink)) { |
| 54 | + $content = "## Management packages - $moniker`r`n" |
| 55 | + $content += "[!INCLUDE [mgmt-packages]($mgmtTableLink)]`r`n" |
| 56 | + } |
| 57 | + if (!$content) { |
| 58 | + return |
| 59 | + } |
| 60 | + $null = New-Item -Path $readmePath -Force |
| 61 | + $lang = $LanguageDisplayName |
| 62 | + $langTitle = "Azure $serviceName SDK for $lang" |
| 63 | + # Generate the front-matter for docs needs |
| 64 | + $metadataString = GenerateDocsMsMetadata -language $lang -langTitle $langTitle -serviceName $serviceName ` |
| 65 | + -tenantId $TenantId -clientId $ClientId -clientSecret $ClientSecret ` |
| 66 | + -msService $msService |
| 67 | + Add-Content -Path $readmePath -Value $metadataString |
| 68 | + |
| 69 | + # Add tables, seperate client and mgmt. |
| 70 | + $readmeHeader = "# $langTitle - $moniker" |
| 71 | + Add-Content -Path $readmePath -Value $readmeHeader |
| 72 | + Add-Content -Path $readmePath -Value $content |
| 73 | +} |
| 74 | + |
| 75 | +function compare-and-merge-metadata ($original, $updated) { |
| 76 | + $originalTable = ConvertFrom-StringData -StringData $original -Delimiter ":" |
| 77 | + $updatedTable = ConvertFrom-StringData -StringData $updated -Delimiter ":" |
| 78 | + foreach ($key in $originalTable.Keys) { |
| 79 | + if (!($updatedTable.ContainsKey($key))) { |
| 80 | + Write-Warning "New metadata missed the entry: $key. Adding back." |
| 81 | + $updated += "$key`: $($originalTable[$key])`r`n" |
| 82 | + } |
| 83 | + } |
| 84 | + return $updated |
| 85 | +} |
| 86 | + |
| 87 | +# Update the metadata table. |
| 88 | +function update-metadata-table($readmeFolder, $readmeName, $serviceName, $msService) |
| 89 | +{ |
| 90 | + $readmePath = Join-Path $readmeFolder -ChildPath $readmeName |
| 91 | + $readmeContent = Get-Content -Path $readmePath -Raw |
| 92 | + $null = $readmeContent -match "---`n*(?<metadata>(.*`n)*)---`n*(?<content>(.*`n)*)" |
| 93 | + $restContent = $Matches["content"] |
| 94 | + $lang = $LanguageDisplayName |
| 95 | + $orignalMetadata = $Matches["metadata"] |
| 96 | + $metadataString = GenerateDocsMsMetadata -language $lang -serviceName $serviceName ` |
| 97 | + -tenantId $TenantId -clientId $ClientId -clientSecret $ClientSecret ` |
| 98 | + -msService $msService |
| 99 | + $null = $metadataString -match "---`n*(?<metadata>(.*`n)*)---" |
| 100 | + $mergedMetadata = compare-and-merge-metadata -original $orignalMetadata -updated $Matches["metadata"] |
| 101 | + Set-Content -Path $readmePath -Value "---`n$mergedMetadata---`n$restContent" -NoNewline |
| 102 | +} |
| 103 | + |
| 104 | +function generate-markdown-table($readmeFolder, $readmeName, $packageInfo, $moniker) { |
| 105 | + $tableHeader = "| Reference | Package | Source |`r`n|---|---|---|`r`n" |
| 106 | + $tableContent = "" |
| 107 | + # Here is the table, the versioned value will |
| 108 | + foreach ($pkg in $packageInfo) { |
| 109 | + $repositoryLink = $RepositoryUri |
| 110 | + $packageLevelReadme = "" |
| 111 | + if (Test-Path "Function:$GetPackageLevelReadmeFn") { |
| 112 | + $packageLevelReadme = &$GetPackageLevelReadmeFn -packageMetadata $pkg |
| 113 | + } |
| 114 | + |
| 115 | + $referenceLink = "[$($pkg.DisplayName)]($packageLevelReadme-readme.md)" |
| 116 | + if (!(Test-Path (Join-Path $readmeFolder -ChildPath "$packageLevelReadme-readme.md"))) { |
| 117 | + $referenceLink = $pkg.DisplayName |
| 118 | + } |
| 119 | + $githubLink = $GithubUri |
| 120 | + if ($pkg.PSObject.Members.Name -contains "DirectoryPath") { |
| 121 | + $githubLink = "$GithubUri/blob/main/$($pkg.DirectoryPath)" |
| 122 | + } |
| 123 | + $line = "|$referenceLink|[$($pkg.Package)]($repositoryLink/$($pkg.Package))|[Github]($githubLink)|`r`n" |
| 124 | + $tableContent += $line |
| 125 | + } |
| 126 | + $readmePath = Join-Path $readmeFolder -ChildPath $readmeName |
| 127 | + if($tableContent) { |
| 128 | + $null = New-Item -Path $readmePath -ItemType File -Force |
| 129 | + Add-Content -Path $readmePath -Value $tableHeader -NoNewline |
| 130 | + Add-Content -Path $readmePath -Value $tableContent -NoNewline |
| 131 | + } |
| 132 | +} |
| 133 | + |
| 134 | +function generate-service-level-readme($readmeBaseName, $pathPrefix, $packageInfos, $serviceName, $moniker) { |
| 135 | + # Add ability to override |
| 136 | + # Fetch the service readme name |
| 137 | + $msService = GetDocsMsService -packageInfo $packageInfos[0] -serviceName $serviceName |
| 138 | + |
| 139 | + $readmeFolder = "$DocRepoLocation/$pathPrefix/$moniker/" |
| 140 | + $serviceReadme = "$readmeBaseName.md" |
| 141 | + $clientIndexReadme = "$readmeBaseName-client-index.md" |
| 142 | + $mgmtIndexReadme = "$readmeBaseName-mgmt-index.md" |
| 143 | + $clientPackageInfo = $packageInfos.Where({ 'client' -eq $_.Type }) | Sort-Object -Property Package |
| 144 | + if ($clientPackageInfo) { |
| 145 | + generate-markdown-table -readmeFolder $readmeFolder -readmeName "$clientIndexReadme" -packageInfo $clientPackageInfo -moniker $moniker |
| 146 | + } |
| 147 | + # TODO: we currently do not have the right decision on how we display mgmt packages. Will track the mgmt work in issue. |
| 148 | + # https://github.com/Azure/azure-sdk-tools/issues/3422 |
| 149 | + # $mgmtPackageInfo = $packageInfos.Where({ 'mgmt' -eq $_.Type }) | Sort-Object -Property Package |
| 150 | + # if ($mgmtPackageInfo) { |
| 151 | + # generate-markdown-table -readmeFolder $readmeFolder -readmeName "$mgmtIndexReadme" -packageInfo $mgmtPackageInfo -moniker $moniker |
| 152 | + # } |
| 153 | + if (!(Test-Path (Join-Path $readmeFolder -ChildPath $serviceReadme))) { |
| 154 | + create-metadata-table -readmeFolder $readmeFolder -readmeName $serviceReadme -moniker $moniker -msService $msService ` |
| 155 | + -clientTableLink $clientIndexReadme -mgmtTableLink $mgmtIndexReadme ` |
| 156 | + -serviceName $serviceName |
| 157 | + } |
| 158 | + else { |
| 159 | + update-metadata-table -readmeFolder $readmeFolder -readmeName $serviceReadme -serviceName $serviceName -msService $msService |
| 160 | + } |
| 161 | +} |
| 162 | + |
| 163 | +$fullMetadata = Get-CSVMetadata |
| 164 | +$monikers = @("latest", "preview") |
| 165 | +foreach($moniker in $monikers) { |
| 166 | + # The onboarded packages return is key-value pair, which key is the package index, and value is the package info from {metadata}.json |
| 167 | + # E.g. |
| 168 | + # Key as: @azure/storage-blob |
| 169 | + # Value as: |
| 170 | + # { |
| 171 | + # "Name": "@azure/storage-blob", |
| 172 | + # "Version": "12.10.0-beta.1", |
| 173 | + # "DevVersion": null, |
| 174 | + # "DirectoryPath": "sdk/storage/storage-blob", |
| 175 | + # "ServiceDirectory": "storage", |
| 176 | + # "ReadMePath": "sdk/storage/storage-blob/README.md", |
| 177 | + # "ChangeLogPath": "sdk/storage/storage-blob/CHANGELOG.md", |
| 178 | + # "Group": null, |
| 179 | + # "SdkType": "client", |
| 180 | + # "IsNewSdk": true, |
| 181 | + # "ArtifactName": "azure-storage-blob", |
| 182 | + # "ReleaseStatus": "2022-04-19" |
| 183 | + # } |
| 184 | + $onboardedPackages = &$GetOnboardedDocsMsPackagesForMonikerFn ` |
| 185 | + -DocRepoLocation $DocRepoLocation -moniker $moniker |
| 186 | + $csvMetadata = @() |
| 187 | + foreach($metadataEntry in $fullMetadata) { |
| 188 | + if ($metadataEntry.Package -and $metadataEntry.Hide -ne 'true') { |
| 189 | + $pkgKey = GetPackageKey $metadataEntry |
| 190 | + if($onboardedPackages.ContainsKey($pkgKey)) { |
| 191 | + if ($onboardedPackages[$pkgKey] -and $onboardedPackages[$pkgKey].DirectoryPath) { |
| 192 | + if (!($metadataEntry.PSObject.Members.Name -contains "DirectoryPath")) { |
| 193 | + Add-Member -InputObject $metadataEntry ` |
| 194 | + -MemberType NoteProperty ` |
| 195 | + -Name DirectoryPath ` |
| 196 | + -Value $onboardedPackages[$pkgKey].DirectoryPath |
| 197 | + } |
| 198 | + } |
| 199 | + $csvMetadata += $metadataEntry |
| 200 | + } |
| 201 | + } |
| 202 | + } |
| 203 | + $packagesForService = @{} |
| 204 | + $allPackages = GetPackageLookup $csvMetadata |
| 205 | + foreach ($metadataKey in $allPackages.Keys) { |
| 206 | + $metadataEntry = $allPackages[$metadataKey] |
| 207 | + if (!$metadataEntry.ServiceName) { |
| 208 | + LogWarning "Empty ServiceName for package `"$metadataKey`". Skipping." |
| 209 | + continue |
| 210 | + } |
| 211 | + $packagesForService[$metadataKey] = $metadataEntry |
| 212 | + } |
| 213 | + $services = @{} |
| 214 | + foreach ($package in $packagesForService.Values) { |
| 215 | + if ($package.ServiceName -eq 'Other') { |
| 216 | + # Skip packages under the service category "Other". Those will be handled |
| 217 | + # later |
| 218 | + continue |
| 219 | + } |
| 220 | + if (!$services.ContainsKey($package.ServiceName)) { |
| 221 | + $services[$package.ServiceName] = $true |
| 222 | + } |
| 223 | + } |
| 224 | + foreach ($service in $services.Keys) { |
| 225 | + Write-Host "Building service: $service" |
| 226 | + |
| 227 | + $servicePackages = $packagesForService.Values.Where({ $_.ServiceName -eq $service }) |
| 228 | + |
| 229 | + |
| 230 | + $serviceReadmeBaseName = ServiceLevelReadmeNameStyle -serviceName $service |
| 231 | + $hrefPrefix = "docs-ref-services" |
| 232 | + |
| 233 | + generate-service-level-readme -readmeBaseName $serviceReadmeBaseName -pathPrefix $hrefPrefix ` |
| 234 | + -packageInfos $servicePackages -serviceName $service -moniker $moniker |
| 235 | + } |
| 236 | +} |
0 commit comments