Sync eng/common directory with azure-sdk-tools for PR 1233 (#1075)

* reformatted parameter arguments to both update-docs scripts. added parameter requirements and renamed CIRepository to DocRepoLocation which is a lot clearer. Added additional CIConfig parameter to update-docs-metadata to support specific write locations per moniker.

Co-authored-by: scbedd <45376673+scbedd@users.noreply.github.com>

eng/common/pipelines/templates/steps/docs-metadata-release.yml

@@ -48,7 +48,7 @@ steps:
       -WorkDirectory "${{ parameters.WorkingDirectory }}"
       -DocRepoLocation "${{ parameters.WorkingDirectory }}/repo"
       -Language "${{parameters.Language}}"
-      -DocRepoContentLocation ${{ parameters.DocRepoDestinationPath }}
+      -Configs "${{ parameters.CIConfigs }}"
     pwsh: true
   env:
     GH_TOKEN: $(azuresdk-github-pat)
@@ -65,7 +65,7 @@ steps:
       -RepoId ${{ parameters.RepoId }}
       -Repository ${{ parameters.PackageRepository }}
       -ReleaseSHA ${{ parameters.ReleaseSha }}
-      -CIRepository "${{ parameters.WorkingDirectory }}/repo"
+      -DocRepoLocation "${{ parameters.WorkingDirectory }}/repo"
       -Configs "${{ parameters.CIConfigs }}"
     pwsh: true
   env:
@@ -107,7 +107,7 @@ steps:
         -RepoId ${{ parameters.RepoId }}
         -Repository ${{ parameters.PackageRepository }}
         -ReleaseSHA ${{ parameters.ReleaseSha }}
-        -CIRepository "${{ parameters.WorkingDirectory }}/repo"
+        -DocRepoLocation "${{ parameters.WorkingDirectory }}/repo"
         -Configs "${{ parameters.CIConfigs }}"
       pwsh: true
     env:

eng/common/scripts/update-docs-ci.ps1

@@ -24,10 +24,10 @@ param (
   $Repository, # EG: "Maven", "PyPI", "NPM"
 
   [Parameter(Mandatory = $true)]
-  $CIRepository,
+  $DocRepoLocation, # the location of the cloned doc repo
 
   [Parameter(Mandatory = $true)]
-  $Configs
+  $Configs # The configuration elements informing important locations within the cloned doc repo
 )
 
 . (Join-Path $PSScriptRoot common.ps1)
@@ -37,7 +37,8 @@ $targets = ($Configs | ConvertFrom-Json).targets
 #{
 # path_to_config:
 # mode:
-# monikerid
+# monikerid:
+# content_folder:
 #}
 
 $apiUrl = "https://api.github.com/repos/$repoId"
@@ -50,13 +51,13 @@ foreach ($config in $targets) {
   if ($config.mode -eq "Preview") { $includePreview = $true } else { $includePreview = $false }
   $pkgsFiltered = $pkgs | ? { $_.IsPrerelease -eq $includePreview}
 
-  if ($pkgs) {
+  if ($pkgsFiltered) {
     Write-Host "Given the visible artifacts, CI updates against $($config.path_to_config) will be processed for the following packages."
     Write-Host ($pkgsFiltered | % { $_.PackageId + " " + $_.PackageVersion })
 
     if ($UpdateDocCIFn -and (Test-Path "Function:$UpdateDocCIFn"))
     {
-      &$UpdateDocCIFn -pkgs $pkgsFiltered -ciRepo $CIRepository -locationInDocRepo $config.path_to_config -monikerId $config.monikerid
+      &$UpdateDocCIFn -pkgs $pkgsFiltered -ciRepo $DocRepoLocation -locationInDocRepo $config.path_to_config -monikerId $config.monikerid
     }
     else
     {

eng/common/scripts/update-docs-metadata.ps1

@@ -2,16 +2,24 @@
 # powershell core is a requirement for successful execution.
 param (
   # arguments leveraged to parse and identify artifacts
+  [Parameter(Mandatory = $true)]
   $ArtifactLocation, # the root of the artifact folder. DevOps $(System.ArtifactsDirectory)
+  [Parameter(Mandatory = $true)]
   $WorkDirectory, # a clean folder that we can work in
+  [Parameter(Mandatory = $true)]
   $ReleaseSHA, # the SHA for the artifacts. DevOps: $(Release.Artifacts.<artifactAlias>.SourceVersion) or $(Build.SourceVersion)
+  [Parameter(Mandatory = $true)]
   $RepoId, # full repo id. EG azure/azure-sdk-for-net  DevOps: $(Build.Repository.Id). Used as a part of VerifyPackages
+  [Parameter(Mandatory = $true)]
   $Repository, # EG: "Maven", "PyPI", "NPM"
 
   # arguments necessary to power the docs release
+  [Parameter(Mandatory = $true)]
   $DocRepoLocation, # the location on disk where we have cloned the documentation repository
+  [Parameter(Mandatory = $true)]
   $Language, # EG: js, java, dotnet. Used in language for the embedded readme.
-  $DocRepoContentLocation = "docs-ref-services/" # within the doc repo, where does our readme go?
+  [Parameter(Mandatory = $true)]
+  $Configs # The configuration elements informing important locations within the cloned doc repo
 )
 
 . (Join-Path $PSScriptRoot common.ps1)
@@ -80,41 +88,52 @@ $pkgs = VerifyPackages -artifactLocation $ArtifactLocation `
   -releaseSha $ReleaseSHA `
   -continueOnError $True
 
-if ($pkgs) {
-  Write-Host "Given the visible artifacts, readmes will be copied for the following packages"
-  Write-Host ($pkgs | % { $_.PackageId })
+$targets = ($Configs | ConvertFrom-Json).targets
 
-  foreach ($packageInfo in $pkgs) {
-    # sync the doc repo
-    $semVer = [AzureEngSemanticVersion]::ParseVersionString($packageInfo.PackageVersion)
-    $rdSuffix = ""
-    if ($semVer.IsPreRelease) {
-      $rdSuffix = "-pre"
-    }
+foreach ($config in $targets) {
+  if ($config.mode -eq "Preview") { $includePreview = $true } else { $includePreview = $false }
+  $pkgsFiltered = $pkgs | ? { $_.IsPrerelease -eq $includePreview}
 
-    $readmeName = "$($packageInfo.PackageId.Replace('azure-','').Replace('Azure.', '').Replace('@azure/', '').ToLower())-readme$rdSuffix.md"
-    $readmeLocation = Join-Path $DocRepoLocation $DocRepoContentLocation $readmeName
+  if ($pkgsFiltered) {
+    Write-Host "Given the visible artifacts, $($config.mode) Readme updates against $($config.path_to_config) will be processed for the following packages."
+    Write-Host ($pkgsFiltered | % { $_.PackageId + " " + $_.PackageVersion })
+  
+    foreach ($packageInfo in $pkgsFiltered) {
+      $readmeName = "$($packageInfo.PackageId.Replace('azure-','').Replace('Azure.', '').Replace('@azure/', '').ToLower())-readme.md"
+      $readmeFolder = Join-Path $DocRepoLocation $config.content_folder
+      $readmeLocation = Join-Path $readmeFolder $readmeName
 
-    if ($packageInfo.ReadmeContent) {
-      $adjustedContent = GetAdjustedReadmeContent -pkgInfo $packageInfo
-    }
-
-    if ($adjustedContent) {
-      try {
-        Push-Location $DocRepoLocation
-        Set-Content -Path $readmeLocation -Value $adjustedContent -Force
-
-        Write-Host "Updated readme for $readmeName."
-      } catch {
-        Write-Host $_
-      } finally {
-        Pop-Location
+      # what happens if this is the first time we've written to this folder? It won't exist. Resolve that.
+      if(!(Test-Path $readmeFolder)) {
+        New-Item -ItemType Directory -Force -Path $readmeFolder
+      }
+
+      if ($packageInfo.ReadmeContent) {
+        $adjustedContent = GetAdjustedReadmeContent -pkgInfo $packageInfo
+      }
+  
+      if ($adjustedContent) {
+        try {
+          Push-Location $DocRepoLocation
+          Set-Content -Path $readmeLocation -Value $adjustedContent -Force
+  
+          Write-Host "Updated readme for $readmeName."
+        } catch {
+          Write-Host $_
+        } finally {
+          Pop-Location
+        }
+      } else {
+        Write-Host "Unable to parse a header out of the readmecontent for PackageId $($packageInfo.PackageId)"
       }
-    } else {
-      Write-Host "Unable to parse a header out of the readmecontent for PackageId $($packageInfo.PackageId)"
     }
   }
+  else {
+    Write-Host "No readmes discovered for $($config.mode) doc release under folder $ArtifactLocation."
+  }
+
+
 }
-else {
-  Write-Host "No readmes discovered for doc release under folder $ArtifactLocation."
-}
+
+
+