...

Text file src/github.com/Azure/azure-sdk-for-go/eng/common/scripts/Update-DocsMsMetadata.ps1

Documentation: github.com/Azure/azure-sdk-for-go/eng/common/scripts

     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