Update mgmt toc structure and modify the service readme (#25082)

Co-authored-by: sima-zhu <sizhu@microsoft.com>
Azure · Jul 5, 2022 · 6d89670 · 6d89670
1 parent fe9553b
commit 6d89670
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 36 deletions.
diff --git a/eng/common/scripts/Helpers/Metadata-Helpers.ps1 b/eng/common/scripts/Helpers/Metadata-Helpers.ps1
@@ -93,12 +93,10 @@ function GetDocsMsService($packageInfo, $serviceName)
   return $service
 }
 
-function GenerateDocsMsMetadata($language, $langTitle = "", $serviceName, $tenantId, $clientId, $clientSecret, $msService) 
+function GenerateDocsMsMetadata($language, $languageDisplayName, $serviceName, $tenantId, $clientId, $clientSecret, $msService) 
 {
-  if (!$langTitle) {
-    $langTitle = "Azure $serviceName SDK for $language"
-  }
-  $langDescription = "Reference for Azure $serviceName SDK for $language"
+  $langTitle = "Azure $serviceName SDK for $languageDisplayName"
+  $langDescription = "Reference for Azure $serviceName SDK for $languageDisplayName"
   # Github url for source code: e.g. https://github.com/Azure/azure-sdk-for-js
   $serviceBaseName = $serviceName.ToLower().Replace(' ', '').Replace('/', '-')
   $author = GetPrimaryCodeOwner -TargetDirectory "/sdk/$serviceBaseName/"
@@ -132,4 +130,4 @@ ms.service: $msService
 
 function ServiceLevelReadmeNameStyle($serviceName) {
   return $serviceName.ToLower().Replace(' ', '-').Replace('/', '-')
-}
+}
diff --git a/eng/common/scripts/Service-Level-Readme-Automation.ps1 b/eng/common/scripts/Service-Level-Readme-Automation.ps1
@@ -51,17 +51,15 @@ function create-metadata-table($readmeFolder, $readmeName, $moniker, $msService,
     $content += "[!INCLUDE [client-packages]($clientTableLink)]`r`n"
   }
   if (Test-Path (Join-Path $readmeFolder -ChildPath $mgmtTableLink)) {
-    $content = "## Management packages - $moniker`r`n"
+    $content += "## Management packages - $moniker`r`n"
     $content += "[!INCLUDE [mgmt-packages]($mgmtTableLink)]`r`n"
   }
   if (!$content) {
     return
   }
-  $null = New-Item -Path $readmePath -Force
-  $lang = $LanguageDisplayName
-  $langTitle = "Azure $serviceName SDK for $lang"
   # Generate the front-matter for docs needs
-  $metadataString = GenerateDocsMsMetadata -language $lang -langTitle $langTitle -serviceName $serviceName `
+  # $Language, $LanguageDisplayName are the variables globally defined in Language-Settings.ps1
+  $metadataString = GenerateDocsMsMetadata -language $Language -languageDisplayName $LanguageDisplayName -serviceName $serviceName `
     -tenantId $TenantId -clientId $ClientId -clientSecret $ClientSecret `
     -msService $msService
   Add-Content -Path $readmePath -Value $metadataString
@@ -91,9 +89,9 @@ function update-metadata-table($readmeFolder, $readmeName, $serviceName, $msServ
   $readmeContent = Get-Content -Path $readmePath -Raw
   $null = $readmeContent -match "---`n*(?<metadata>(.*`n)*)---`n*(?<content>(.*`n)*)"
   $restContent = $Matches["content"]
-  $lang = $LanguageDisplayName
   $orignalMetadata = $Matches["metadata"]
-  $metadataString = GenerateDocsMsMetadata -language $lang -serviceName $serviceName `
+  # $Language, $LanguageDisplayName are the variables globally defined in Language-Settings.ps1
+  $metadataString = GenerateDocsMsMetadata -language $Language -languageDisplayName $LanguageDisplayName -serviceName $serviceName `
     -tenantId $TenantId -clientId $ClientId -clientSecret $ClientSecret `
     -msService $msService
   $null = $metadataString -match "---`n*(?<metadata>(.*`n)*)---"
@@ -144,12 +142,11 @@ function generate-service-level-readme($readmeBaseName, $pathPrefix, $packageInf
   if ($clientPackageInfo) {
     generate-markdown-table -readmeFolder $readmeFolder -readmeName "$clientIndexReadme" -packageInfo $clientPackageInfo -moniker $moniker
   }
-  # TODO: we currently do not have the right decision on how we display mgmt packages. Will track the mgmt work in issue. 
-  # https://github.com/Azure/azure-sdk-tools/issues/3422
-  # $mgmtPackageInfo = $packageInfos.Where({ 'mgmt' -eq $_.Type }) | Sort-Object -Property Package
-  # if ($mgmtPackageInfo) {
-  #   generate-markdown-table -readmeFolder $readmeFolder -readmeName "$mgmtIndexReadme" -packageInfo $mgmtPackageInfo -moniker $moniker
-  # }
+
+  $mgmtPackageInfo = $packageInfos.Where({ 'mgmt' -eq $_.Type }) | Sort-Object -Property Package
+  if ($mgmtPackageInfo) {
+    generate-markdown-table -readmeFolder $readmeFolder -readmeName "$mgmtIndexReadme" -packageInfo $mgmtPackageInfo -moniker $moniker
+  }
   if (!(Test-Path (Join-Path $readmeFolder -ChildPath $serviceReadme))) {
     create-metadata-table -readmeFolder $readmeFolder -readmeName $serviceReadme -moniker $moniker -msService $msService `
       -clientTableLink $clientIndexReadme -mgmtTableLink $mgmtIndexReadme `
@@ -225,8 +222,6 @@ foreach($moniker in $monikers) {
     Write-Host "Building service: $service"
 
     $servicePackages = $packagesForService.Values.Where({ $_.ServiceName -eq $service })
-
-
     $serviceReadmeBaseName = ServiceLevelReadmeNameStyle -serviceName $service
     $hrefPrefix = "docs-ref-services"
 

diff --git a/eng/common/scripts/Update-DocsMsToc.ps1 b/eng/common/scripts/Update-DocsMsToc.ps1
@@ -18,8 +18,8 @@ ToC node layout:
   * Client Package 2 (package level overview page)
   ...
   * Management
-    * Management Package 1
-    * Management Package 2
+    * Management Package 1 (package level overview page)
+    * Management Package 2 (package level overview page)
     ...
 
 .PARAMETER DocRepoLocation
@@ -45,9 +45,9 @@ Install-ModuleIfNotInstalled "powershell-yaml" "0.4.1" | Import-Module
 
 Set-StrictMode -Version 3
 
-function GetClientPackageNode($clientPackage) {
+function GetPackageNode($package) {
   $packageInfo = &$GetDocsMsTocDataFn `
-    -packageMetadata $clientPackage `
+    -packageMetadata $package `
     -docRepoLocation $DocRepoLocation
 
   return [PSCustomObject]@{
@@ -181,22 +181,20 @@ foreach ($service in $serviceNameList) {
   $clientPackages = $packagesForToc.Values.Where({ $_.ServiceName -eq $service -and ('client' -eq $_.Type) })
   $clientPackages = $clientPackages | Sort-Object -Property Package
   foreach ($clientPackage in $clientPackages) {
-    $packageItems += GetClientPackageNode -clientPackage $clientPackage
+    $packageItems += GetPackageNode -package $clientPackage
   }
 
   # All management packages go under a single `Management` header in the ToC
   $mgmtPackages = $packagesForToc.Values.Where({ $_.ServiceName -eq $service -and ('mgmt' -eq $_.Type) })
   $mgmtPackages = $mgmtPackages | Sort-Object -Property Package
-  if ($mgmtPackages) {
-    $children = &$GetDocsMsTocChildrenForManagementPackagesFn `
-      -packageMetadata $mgmtPackages `
-      -docRepoLocation $DocRepoLocation
-
+  $mgmtItems = @()
+  foreach ($pkg in $mgmtPackages) {
+    $mgmtItems += GetPackageNode -package $pkg
+  }
+  if ($mgmtItems) {
     $packageItems += [PSCustomObject]@{
       name     = 'Management'
-      # There could be multiple packages, ensure this is treated as an array
-      # even if it is a single package
-      children = @($children)
+      items    = $mgmtItems
     }
   }
 
@@ -266,12 +264,12 @@ if ($otherPackages) {
 
       if ($null -ne $currentNode) {
         $otherPackage.DisplayName = $segments[$segments.Count - 1]
-        $currentNode.Add((GetClientPackageNode $otherPackage))
+        $currentNode.Add((GetPackageNode $otherPackage))
       }
 
     }
     else {
-      $otherPackageItems.Add((GetClientPackageNode $otherPackage))
+      $otherPackageItems.Add((GetPackageNode $otherPackage))
     }
   }
 }