From 7f8c23129656510ef93e81aff584e43b59b83d90 Mon Sep 17 00:00:00 2001 From: Wes Haggard Date: Thu, 16 Jan 2025 15:36:37 -0800 Subject: [PATCH 1/6] Update github.io docs to use static website instead of blobs directly --- .../docgeneration/templates/matthews/styles/main.js | 10 +++++----- eng/common/pipelines/templates/jobs/docindex.yml | 9 ++++++--- eng/common/scripts/copy-docs-to-blobstorage.ps1 | 2 +- .../apiview-gpt/guidelines/python/design.json | 6 +++--- .../apiview-gpt/guidelines/python/implementation.json | 2 +- 5 files changed, 16 insertions(+), 13 deletions(-) diff --git a/eng/common/docgeneration/templates/matthews/styles/main.js b/eng/common/docgeneration/templates/matthews/styles/main.js index 7ab1dd9e28f..2bda06d0c2e 100644 --- a/eng/common/docgeneration/templates/matthews/styles/main.js +++ b/eng/common/docgeneration/templates/matthews/styles/main.js @@ -108,7 +108,7 @@ function httpGetAsyncFallbackOnFail(targetUrl, successCallback, failureCallback) } function populateOptions(selector, packageName) { - var versionRequestUrl = "https://azuresdkdocs.blob.core.windows.net/$web/" + SELECTED_LANGUAGE + "/" + packageName + "/versioning/versions" + var versionRequestUrl = "https://azuresdkdocs.z19.web.core.windows.net/" + SELECTED_LANGUAGE + "/" + packageName + "/versioning/versions" httpGetAsync(versionRequestUrl, function (responseText) { var versionselector = document.createElement("select") @@ -181,9 +181,9 @@ function loadedOtherVersions(url, latestVersions, publishedVersions, selector, c } function populateIndexList(selector, packageName) { - var url = "https://azuresdkdocs.blob.core.windows.net/$web/" + SELECTED_LANGUAGE + "/" + packageName + "/versioning/versions" - var latestGAUrl = "https://azuresdkdocs.blob.core.windows.net/$web/" + SELECTED_LANGUAGE + "/" + packageName + "/versioning/latest-ga" - var latestPreviewUrl = "https://azuresdkdocs.blob.core.windows.net/$web/" + SELECTED_LANGUAGE + "/" + packageName + "/versioning/latest-preview" + var url = "https://azuresdkdocs.z19.web.core.windows.net/" + SELECTED_LANGUAGE + "/" + packageName + "/versioning/versions" + var latestGAUrl = "https://azuresdkdocs.z19.web.core.windows.net/" + SELECTED_LANGUAGE + "/" + packageName + "/versioning/latest-ga" + var latestPreviewUrl = "https://azuresdkdocs.z19.web.core.windows.net/" + SELECTED_LANGUAGE + "/" + packageName + "/versioning/latest-preview" var latestVersions = document.createElement("ul") httpGetLatestAsync(latestGAUrl, latestVersions, packageName) httpGetLatestAsync(latestPreviewUrl, latestVersions, packageName) @@ -217,7 +217,7 @@ function populateIndexList(selector, packageName) { } function getPackageUrl(language, package, version) { - return "https://azuresdkdocs.blob.core.windows.net/$web/" + language + "/" + package + "/" + version + "/index.html" + return "https://azuresdkdocs.z19.web.core.windows.net/" + language + "/" + package + "/" + version + "/index.html" } // Populate Versions diff --git a/eng/common/pipelines/templates/jobs/docindex.yml b/eng/common/pipelines/templates/jobs/docindex.yml index 8ba898e4c14..d4491cd12df 100644 --- a/eng/common/pipelines/templates/jobs/docindex.yml +++ b/eng/common/pipelines/templates/jobs/docindex.yml @@ -15,12 +15,15 @@ jobs: workingDirectory: $(Build.BinariesDirectory) displayName: Download and Extract DocFX - - task: PowerShell@2 + - task: AzurePowerShell@5 displayName: 'Generate Doc Index' inputs: + azureSubscription: 'Azure SDK Artifacts' + azurePowerShellVersion: latestVersion pwsh: true - filePath: $(Build.SourcesDirectory)/eng/common/docgeneration/Generate-DocIndex.ps1 - arguments: > + ScriptType: 'FilePath' + ScriptPath: $(Build.SourcesDirectory)/eng/common/docgeneration/Generate-DocIndex.ps1 + ScriptArguments: > -Docfx $(docfxPath) -RepoRoot $(Build.SourcesDirectory) -DocGenDir "$(Build.SourcesDirectory)/eng/common/docgeneration" diff --git a/eng/common/scripts/copy-docs-to-blobstorage.ps1 b/eng/common/scripts/copy-docs-to-blobstorage.ps1 index c4f88ce756f..94742a0ce79 100644 --- a/eng/common/scripts/copy-docs-to-blobstorage.ps1 +++ b/eng/common/scripts/copy-docs-to-blobstorage.ps1 @@ -116,7 +116,7 @@ function Get-Existing-Versions Param ( [Parameter(Mandatory=$true)] [String]$PkgName ) - $versionUri = "${BlobAccountName}/`$web/$($Language)/$($PkgName)/versioning/versions" + $versionUri = "https://azuresdkdocs.z19.web.core.windows.net/$($Language)/$($PkgName)/versioning/versions" LogDebug "Heading to $versionUri to retrieve known versions" try { diff --git a/packages/python-packages/apiview-gpt/guidelines/python/design.json b/packages/python-packages/apiview-gpt/guidelines/python/design.json index bab818fac6b..f2ceff00bb0 100644 --- a/packages/python-packages/apiview-gpt/guidelines/python/design.json +++ b/packages/python-packages/apiview-gpt/guidelines/python/design.json @@ -47,7 +47,7 @@ { "id": "python_design.html#python-client-constructor-transport-argument", "category": "Client configuration", - "text": "DO allow users to pass in a transport keyword-only argument that allows the caller to specify a specific transport instance. The default value should be the RequestsTransport (https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/1.1.1/azure.core.pipeline.transport.html?highlight=transport#azure.core.pipeline.transport.RequestsTransport) for synchronous clients and the AioHttpTransport (https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/1.1.1/azure.core.pipeline.transport.html?highlight=transport#azure.core.pipeline.transport.AioHttpTransport) for async clients." + "text": "DO allow users to pass in a transport keyword-only argument that allows the caller to specify a specific transport instance. The default value should be the RequestsTransport (https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/1.1.1/azure.core.pipeline.transport.html?highlight=transport#azure.core.pipeline.transport.RequestsTransport) for synchronous clients and the AioHttpTransport (https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/1.1.1/azure.core.pipeline.transport.html?highlight=transport#azure.core.pipeline.transport.AioHttpTransport) for async clients." }, { "id": "python_design.html#python-client-connection-string", @@ -282,7 +282,7 @@ { "id": "python_design.html#python-errors-azure-exceptions", "category": "Exceptions", - "text": "YOU SHOULD prefer raising existing exception types from the azure-core (https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/1.9.0/index.html#azure-core-library-exceptions) package over creating new exception types." + "text": "YOU SHOULD prefer raising existing exception types from the azure-core (https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/1.9.0/index.html#azure-core-library-exceptions) package over creating new exception types." }, { "id": "python_design.html#python-errors-use-standard-exceptions", @@ -292,7 +292,7 @@ { "id": "python_design.html#python-errors-new-exceptions", "category": "Exceptions", - "text": "YOU SHOULD NOT create a new exception type unless the developer can handle the error programmatically. Specialized exception types related to service operation failures should be based on existing exception types from the azure-core (https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/1.9.0/index.html#azure-core-library-exceptions) package.\n\nFor higher-level methods that use multiple HTTP requests, either the last exception or an aggregate exception of all failures should be produced." + "text": "YOU SHOULD NOT create a new exception type unless the developer can handle the error programmatically. Specialized exception types related to service operation failures should be based on existing exception types from the azure-core (https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/1.9.0/index.html#azure-core-library-exceptions) package.\n\nFor higher-level methods that use multiple HTTP requests, either the last exception or an aggregate exception of all failures should be produced." }, { "id": "python_design.html#python-errors-rich-info", diff --git a/packages/python-packages/apiview-gpt/guidelines/python/implementation.json b/packages/python-packages/apiview-gpt/guidelines/python/implementation.json index 55bd38b99cd..bf1b37ce204 100644 --- a/packages/python-packages/apiview-gpt/guidelines/python/implementation.json +++ b/packages/python-packages/apiview-gpt/guidelines/python/implementation.json @@ -22,7 +22,7 @@ { "id": "python_implementation.html#python-custom-policy-base-class", "category": "Custom policies", - "text": "DO derive from HTTPPolicy (https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/1.9.0/azure.core.pipeline.policies.html#azure.core.pipeline.policies.HTTPPolicy) AsyncHTTPPolicy (https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/1.9.0/azure.core.pipeline.policies.html#azure.core.pipeline.policies.AsyncHTTPPolicy) (if you need to make network calls) or SansIOHTTPPolicy (https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/1.9.0/azure.core.pipeline.policies.html#azure.core.pipeline.policies.SansIOHTTPPolicy) (if you do not)." + "text": "DO derive from HTTPPolicy (https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/1.9.0/azure.core.pipeline.policies.html#azure.core.pipeline.policies.HTTPPolicy) AsyncHTTPPolicy (https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/1.9.0/azure.core.pipeline.policies.html#azure.core.pipeline.policies.AsyncHTTPPolicy) (if you need to make network calls) or SansIOHTTPPolicy (https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/1.9.0/azure.core.pipeline.policies.html#azure.core.pipeline.policies.SansIOHTTPPolicy) (if you do not)." }, { "id": "python_implementation.html#python-custom-policy-thread-safe", From 6c15e1f7822a9d3f6c8807c2644c31be2f3fc579 Mon Sep 17 00:00:00 2001 From: Wes Haggard Date: Fri, 17 Jan 2025 11:02:51 -0800 Subject: [PATCH 2/6] Update eng/common/scripts/copy-docs-to-blobstorage.ps1 Co-authored-by: Ben Broderick Phillips --- eng/common/scripts/copy-docs-to-blobstorage.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/common/scripts/copy-docs-to-blobstorage.ps1 b/eng/common/scripts/copy-docs-to-blobstorage.ps1 index 94742a0ce79..bfcae988b87 100644 --- a/eng/common/scripts/copy-docs-to-blobstorage.ps1 +++ b/eng/common/scripts/copy-docs-to-blobstorage.ps1 @@ -116,7 +116,7 @@ function Get-Existing-Versions Param ( [Parameter(Mandatory=$true)] [String]$PkgName ) - $versionUri = "https://azuresdkdocs.z19.web.core.windows.net/$($Language)/$($PkgName)/versioning/versions" + $versionUri = "https://azuresdkdocs.z19.web.core.windows.net/$Language/$PkgName/versioning/versions" LogDebug "Heading to $versionUri to retrieve known versions" try { From c877f43a31278cd52ca68db9a1be705bc0941208 Mon Sep 17 00:00:00 2001 From: Wes Haggard Date: Mon, 20 Jan 2025 11:27:18 -0800 Subject: [PATCH 3/6] Switch from AzurePowerShell to AzureCLI task --- .../pipelines/templates/jobs/docindex.yml | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/eng/common/pipelines/templates/jobs/docindex.yml b/eng/common/pipelines/templates/jobs/docindex.yml index d4491cd12df..6b5be7e0ece 100644 --- a/eng/common/pipelines/templates/jobs/docindex.yml +++ b/eng/common/pipelines/templates/jobs/docindex.yml @@ -15,20 +15,18 @@ jobs: workingDirectory: $(Build.BinariesDirectory) displayName: Download and Extract DocFX - - task: AzurePowerShell@5 + - task: AzureCLI@2 displayName: 'Generate Doc Index' inputs: azureSubscription: 'Azure SDK Artifacts' - azurePowerShellVersion: latestVersion - pwsh: true - ScriptType: 'FilePath' - ScriptPath: $(Build.SourcesDirectory)/eng/common/docgeneration/Generate-DocIndex.ps1 - ScriptArguments: > - -Docfx $(docfxPath) - -RepoRoot $(Build.SourcesDirectory) - -DocGenDir "$(Build.SourcesDirectory)/eng/common/docgeneration" - -DocOutDir "$(Build.ArtifactStagingDirectory)/docfx_project" - -verbose + scriptType: pscore + inlineScript: > + $(Build.SourcesDirectory)/eng/common/docgeneration/Generate-DocIndex.ps1 + -Docfx $(docfxPath) + -RepoRoot $(Build.SourcesDirectory) + -DocGenDir "$(Build.SourcesDirectory)/eng/common/docgeneration" + -DocOutDir "$(Build.ArtifactStagingDirectory)/docfx_project" + -verbose - template: /eng/common/pipelines/templates/steps/mashup-doc-index.yml parameters: From 3fb3c949b21ac701b9176bb43814f0ba5892f93c Mon Sep 17 00:00:00 2001 From: Wes Haggard Date: Mon, 20 Jan 2025 12:21:29 -0800 Subject: [PATCH 4/6] Add scriptLocation to docindex.yml --- eng/common/pipelines/templates/jobs/docindex.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/eng/common/pipelines/templates/jobs/docindex.yml b/eng/common/pipelines/templates/jobs/docindex.yml index 6b5be7e0ece..0caf7a9bec9 100644 --- a/eng/common/pipelines/templates/jobs/docindex.yml +++ b/eng/common/pipelines/templates/jobs/docindex.yml @@ -20,6 +20,7 @@ jobs: inputs: azureSubscription: 'Azure SDK Artifacts' scriptType: pscore + scriptLocation: inlineScript inlineScript: > $(Build.SourcesDirectory)/eng/common/docgeneration/Generate-DocIndex.ps1 -Docfx $(docfxPath) From 7a819c8b7aff0369b3f6921be15902f720c9bc27 Mon Sep 17 00:00:00 2001 From: Wes Haggard Date: Mon, 20 Jan 2025 13:32:20 -0800 Subject: [PATCH 5/6] Update Generate-DocIndex.ps1 --- eng/common/docgeneration/Generate-DocIndex.ps1 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/eng/common/docgeneration/Generate-DocIndex.ps1 b/eng/common/docgeneration/Generate-DocIndex.ps1 index 2b8d59468ba..a279a293451 100644 --- a/eng/common/docgeneration/Generate-DocIndex.ps1 +++ b/eng/common/docgeneration/Generate-DocIndex.ps1 @@ -25,13 +25,14 @@ function Get-BlobStorage-Artifacts( # "--query '[].name'" returns a list of only blob names # "--num-results *" handles pagination so the caller does not have to $artifacts = az storage blob list ` + --auth-mode login ` --account-name $storageAccountName ` --container-name $storageContainerName ` --prefix $storagePrefix ` --delimiter / ` --only-show-errors ` --query '[].name' ` - --num-results * | ConvertFrom-Json + --num-results * | ConvertFrom-Json LogDebug "Number of artifacts found: $($artifacts.Length)" # example: "python/azure-storage-blob" -> "azure-storage-blob" From 84b6184a84c39cbcf3425b5f67c5f1784f291853 Mon Sep 17 00:00:00 2001 From: Wes Haggard Date: Mon, 20 Jan 2025 14:40:15 -0800 Subject: [PATCH 6/6] Fix indentation in docindex.yml script block --- eng/common/pipelines/templates/jobs/docindex.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/eng/common/pipelines/templates/jobs/docindex.yml b/eng/common/pipelines/templates/jobs/docindex.yml index 0caf7a9bec9..45c19dc2100 100644 --- a/eng/common/pipelines/templates/jobs/docindex.yml +++ b/eng/common/pipelines/templates/jobs/docindex.yml @@ -23,11 +23,11 @@ jobs: scriptLocation: inlineScript inlineScript: > $(Build.SourcesDirectory)/eng/common/docgeneration/Generate-DocIndex.ps1 - -Docfx $(docfxPath) - -RepoRoot $(Build.SourcesDirectory) - -DocGenDir "$(Build.SourcesDirectory)/eng/common/docgeneration" - -DocOutDir "$(Build.ArtifactStagingDirectory)/docfx_project" - -verbose + -Docfx $(docfxPath) + -RepoRoot $(Build.SourcesDirectory) + -DocGenDir "$(Build.SourcesDirectory)/eng/common/docgeneration" + -DocOutDir "$(Build.ArtifactStagingDirectory)/docfx_project" + -verbose - template: /eng/common/pipelines/templates/steps/mashup-doc-index.yml parameters: