From 96df97de2e91799ec3415f7bf1c268ddcca11ec6 Mon Sep 17 00:00:00 2001 From: chunyu3 Date: Fri, 29 Apr 2022 16:00:47 +0800 Subject: [PATCH] refine readme files, add error checking in outer script --- .../automation/GenerateAndBuildLib.ps1 | 2 +- .../Invoke-DataPlaneGenerateSDKPackage.ps1 | 9 +++- .../.content/packageResource/README.md | 25 ++++------ .../.content/samples/Sample1_HelloWorld.md | 8 +--- .../samples/Sample1_HelloWorldAsync.md | 8 +--- .../.content/testResource/ci.yml | 8 ++-- .../.content/testResource/tests.yml | 2 +- .../.template.config/template.json | 46 +++++++++++++++++-- sdk/template/Azure.Template/README.md | 24 +++------- 9 files changed, 77 insertions(+), 55 deletions(-) diff --git a/eng/scripts/automation/GenerateAndBuildLib.ps1 b/eng/scripts/automation/GenerateAndBuildLib.ps1 index bba03db01055..da3ba7600351 100644 --- a/eng/scripts/automation/GenerateAndBuildLib.ps1 +++ b/eng/scripts/automation/GenerateAndBuildLib.ps1 @@ -277,7 +277,7 @@ function Invoke-Generate() { Push-Location $sdkfolder/src dotnet build /t:GenerateCode if ( !$? ) { - Write-Error "Failed to create generate sdk." + Write-Error "Failed to generate sdk." Pop-Location exit 1 } diff --git a/eng/scripts/automation/Invoke-DataPlaneGenerateSDKPackage.ps1 b/eng/scripts/automation/Invoke-DataPlaneGenerateSDKPackage.ps1 index ac9510f481f3..faf6770567bb 100644 --- a/eng/scripts/automation/Invoke-DataPlaneGenerateSDKPackage.ps1 +++ b/eng/scripts/automation/Invoke-DataPlaneGenerateSDKPackage.ps1 @@ -24,9 +24,16 @@ Write-Host "projectFolder:$projectFolder" Remove-Item $outputJsonFile # Generate Code Invoke-Generate -sdkfolder $projectFolder +if ( !$? ) { + Write-Error "Failed to generate sdk." + exit 1 +} # Build Invoke-Build -sdkfolder $projectFolder - +if ( !$? ) { + Write-Error "Failed to build sdk. exit code: $?" + exit 1 +} # Generate APIs $repoRoot = (Join-Path $PSScriptRoot .. .. ..) Set-Location $repoRoot diff --git a/sdk/template/Azure.Template/.content/packageResource/README.md b/sdk/template/Azure.Template/.content/packageResource/README.md index 830f13e14c77..8bc0a224e4c7 100644 --- a/sdk/template/Azure.Template/.content/packageResource/README.md +++ b/sdk/template/Azure.Template/.content/packageResource/README.md @@ -1,24 +1,11 @@ -# README.md template - -Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [Azure.Template/README.md](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/README.md) for an example following this template. - -**Title**: The H1 of your README should be in the format: `# [Product Name] client library for [Language]` - -* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for .NET` - # Azure Template client library for .NET -**Introduction**: The introduction appears directly under the title (H1) of your README. +This section should give out brief introduction of the client library. -* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. * First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). * Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. -* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): - [Source code](https://github.com/Azure/azure-sdk-for-net/tree/bb0fbccfc33dd27d1ec6f0870022824d47181e61/sdk/template-dpg/Azure.ServiceTemplate.Template/src) | [Package (NuGet)](https://www.nuget.org/packages/Azure.AI.AnomalyDetector) | [API reference documentation](https://azure.github.io/azure-sdk-for-net/anomalydetector.html) | [Product documentation](https://docs.microsoft.com/azure/cognitive-services/anomaly-detector/) - -> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. + [Source code](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/src) | [Package (NuGet)](https://www.nuget.org/packages/Azure.Template) | [API reference documentation](https://azure.github.io/azure-sdk-for-net) | [Product documentation](https://docs.microsoft.com/azure) ## Getting started @@ -28,6 +15,12 @@ This section should include everything a developer needs to do to install and cr First, provide instruction for obtaining and installing the package or library. This section might include only a single line of code, like `dotnet add package package-name`, but should enable a developer to successfully install the package from NuGet, npm, or even cloning a GitHub repository. +Install the client library for .NET with [NuGet](https://www.nuget.org/ ): + +```dotnetcli +dotnet add package Azure.Template --prerelease +``` + ### Prerequisites Include a section after the install command that details any requirements that must be satisfied before a developer can [authenticate](#authenticate-the-client) and test all of the snippets in the [Examples](#examples) section. For example, for Cosmos DB: @@ -94,4 +87,4 @@ This is a template, but your SDK readme should include details on how to contrib [style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization [style-guide-cloud]: https://aka.ms/azsdk/cloud-style-guide -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftemplate%2FAzure.Template%2FREADME.png) \ No newline at end of file +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net/sdk/template/Azure.Template/README.png) \ No newline at end of file diff --git a/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorld.md b/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorld.md index 31d46e0c573e..84637e9c2779 100644 --- a/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorld.md +++ b/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorld.md @@ -1,10 +1,6 @@ -# Sample readme template +# -Use the guidelines in each section of this template to write samples, for an example following this template. - -This sample shows how to detect all the anomalies in the entire time series. - -To get started, make sure you have satisfied all the prerequisites and got all the resources required by [README][README]. +To use these samples, you'll first need to set up resources. See [getting started](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/README.md#getting-started) for details. ## diff --git a/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorldAsync.md b/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorldAsync.md index 5eefdba0de56..0bb00e0cad10 100644 --- a/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorldAsync.md +++ b/sdk/template/Azure.Template/.content/samples/Sample1_HelloWorldAsync.md @@ -1,10 +1,6 @@ -# Sample readme template +# -Use the guidelines in each section of this template to write samples, for an example following this template. - -This sample shows how to detect all the anomalies in the entire time series. - -To get started, make sure you have satisfied all the prerequisites and got all the resources required by [README][README]. +To use these samples, you'll first need to set up resources. See [getting started](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/README.md#getting-started) for details. ## asynchronously diff --git a/sdk/template/Azure.Template/.content/testResource/ci.yml b/sdk/template/Azure.Template/.content/testResource/ci.yml index 3b231da207ab..39167577452f 100644 --- a/sdk/template/Azure.Template/.content/testResource/ci.yml +++ b/sdk/template/Azure.Template/.content/testResource/ci.yml @@ -8,7 +8,7 @@ trigger: - release/* paths: include: - - sdk/ServiceNameLowercase/ + - sdk/template/ pr: branches: @@ -19,13 +19,13 @@ pr: - release/* paths: include: - - sdk/ServiceNameLowercase/ + - sdk/template/ extends: template: /eng/pipelines/templates/stages/archetype-sdk-client.yml parameters: - ServiceDirectory: ServiceNameLowercase + ServiceDirectory: template ArtifactName: packages Artifacts: - name: Azure.Template - safeName: PackageSafeName + safeName: AzureTemplate diff --git a/sdk/template/Azure.Template/.content/testResource/tests.yml b/sdk/template/Azure.Template/.content/testResource/tests.yml index 7f4825e231c9..6c539b353599 100644 --- a/sdk/template/Azure.Template/.content/testResource/tests.yml +++ b/sdk/template/Azure.Template/.content/testResource/tests.yml @@ -3,5 +3,5 @@ trigger: none extends: template: /eng/pipelines/templates/stages/archetype-sdk-tests.yml parameters: - ServiceDirectory: ServiceNameLowercase + ServiceDirectory: template SupportedClouds: 'Public' diff --git a/sdk/template/Azure.Template/.template.config/template.json b/sdk/template/Azure.Template/.template.config/template.json index b804f01d18d8..735549fd09ff 100644 --- a/sdk/template/Azure.Template/.template.config/template.json +++ b/sdk/template/Azure.Template/.template.config/template.json @@ -193,12 +193,29 @@ "datatype": "text", "valueSource": "libraryName", "valueTransform": "ServiceNameLowerForm", - "replaces": "ServiceNameLowercase" + "replaces": "template" }, + "ServiceDirectoryPath": { + "type": "generated", + "generator": "join", + "parameters": { + "symbols": [ + { + "type": "const", + "value": "sdk/" + }, + { + "type": "ref", + "value": "ServiceNameLowercase" + } + ], + "separator": "" + }, + "replaces": "sdk/template" + }, "PackageSafeName": { "type": "generated", "generator": "join", - "replaces": "PackageSafeName", "parameters": { "symbols": [ { @@ -215,7 +232,30 @@ } ], "separator": "" - } + }, + "replaces": "AzureTemplate" + }, + "PackageNameUnderscored": { + "type": "generated", + "generator": "join", + "parameters": { + "symbols": [ + { + "type": "const", + "value": "Azure" + }, + { + "type": "ref", + "value": "groupName" + }, + { + "type": "ref", + "value": "libraryName" + } + ], + "separator": "_" + }, + "replaces": "Azure_Template" }, "securityTypes": { "type": "generated", diff --git a/sdk/template/Azure.Template/README.md b/sdk/template/Azure.Template/README.md index e31e2d7bd870..efa7930b5893 100644 --- a/sdk/template/Azure.Template/README.md +++ b/sdk/template/Azure.Template/README.md @@ -1,24 +1,14 @@ -# README.md template - -Use the guidelines in each section of this template to ensure consistency and readability of your README. The README resides in your package's GitHub repository at the root of its directory within the repo. It's also used as the package distribution page (NuGet, PyPi, npm, etc.) and as a Quickstart on docs.microsoft.com. See [Azure.Template/README.md](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/README.md) for an example following this template. - -**Title**: The H1 of your README should be in the format: `# [Product Name] client library for [Language]` - -* All headings, including the H1, should use **sentence-style capitalization**. Refer to the [Microsoft Style Guide][style-guide-msft] and [Microsoft Cloud Style Guide][style-guide-cloud] for more information. -* Example: `# Azure Batch client library for .NET` - # Azure Template client library for .NET -**Introduction**: The introduction appears directly under the title (H1) of your README. +Azure Template is a managed service that helps developers get secret simply and securely. + +Use the client library for to: -* **DO NOT** use an "Introduction" or "Overview" heading (H2) for this section. -* First sentence: **Describe the service** briefly. You can usually use the first line of the service's docs landing page for this (Example: [Cosmos DB docs landing page](https://docs.microsoft.com/azure/cosmos-db/)). -* Next, add a **bulleted list** of the **most common tasks** supported by the package or library, prefaced with "Use the client library for [Product Name] to:". Then, provide code snippets for these tasks in the [Examples](#examples) section later in the document. Keep the task list short but include those tasks most developers need to perform with your package. -* Include this single line of links targeting your product's content at the bottom of the introduction, making any adjustments as necessary (for example, NuGet instead of PyPi): +* [Get secret](https://docs.microsoft.com/azure) - [Source code](https://github.com/Azure/azure-sdk-for-net/tree/bb0fbccfc33dd27d1ec6f0870022824d47181e61/sdk/template-dpg/Azure.ServiceTemplate.Template/src) | [Package (NuGet)](https://www.nuget.org/packages/Azure.AI.AnomalyDetector) | [API reference documentation](https://azure.github.io/azure-sdk-for-net/anomalydetector.html) | [Product documentation](https://docs.microsoft.com/azure/cognitive-services/anomaly-detector/) +[Source code][source_root] | [Package (NuGet)][package] | [API reference documentation][reference_docs] | [Product documentation][azconfig_docs] | [Samples][source_samples] -> TIP: Your README should be as **brief** as possible but **no more brief** than necessary to get a developer new to Azure, the service, or the package up and running quickly. Keep it brief, but include everything a developer needs to make their first API call successfully. + [Source code](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/template/Azure.Template/src) | [Package (NuGet)](https://www.nuget.org/packages) | [API reference documentation](https://azure.github.io/azure-sdk-for-net) | [Product documentation](https://docs.microsoft.com/azure) ## Getting started @@ -108,4 +98,4 @@ This is a template, but your SDK readme should include details on how to contrib [style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization [style-guide-cloud]: https://aka.ms/azsdk/cloud-style-guide -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Ftemplate%2FAzure.Template%2FREADME.png) \ No newline at end of file +![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net/sdk/template/Azure.Template/README.png) \ No newline at end of file