From a182f0fbd692f7c153a9720f8d604db0364c0c59 Mon Sep 17 00:00:00 2001 From: Laren-AWS <57545972+Laren-AWS@users.noreply.github.com> Date: Thu, 12 Dec 2024 15:32:39 -0800 Subject: [PATCH] Tools & meta: add complex categories feature, update tools release, update READMEs (#7156) --- .github/workflows/validate-doc-metadata.yml | 2 +- .tools/readmes/config.py | 1 + .tools/readmes/includes/code_examples.jinja2 | 7 ++++ .tools/readmes/render.py | 34 ++++++++++++++++--- dotnetv3/Glacier/README.md | 8 ++--- dotnetv3/MediaConvert/README.md | 4 +-- gov2/bedrock-runtime/README.md | 8 ++--- gov2/cognito/README.md | 8 ++--- .../example_code/bedrock-runtime/README.md | 8 ++--- .../cognito-identity-provider/README.md | 8 ++--- .../elastic-load-balancing-v2/README.md | 8 ++--- javav2/example_code/kms/README.md | 4 +-- .../com/example/s3/directorybucket/README.md | 8 ++--- php/example_code/kms/README.md | 4 +-- python/example_code/cognito/README.md | 8 ++--- .../elastic-load-balancing/README.md | 8 ++--- ruby/example_code/cognito/README.md | 8 ++--- 17 files changed, 85 insertions(+), 51 deletions(-) diff --git a/.github/workflows/validate-doc-metadata.yml b/.github/workflows/validate-doc-metadata.yml index 0c0fe43e61f..506a967af3a 100644 --- a/.github/workflows/validate-doc-metadata.yml +++ b/.github/workflows/validate-doc-metadata.yml @@ -16,7 +16,7 @@ jobs: - name: checkout repo content uses: actions/checkout@v4 - name: validate metadata - uses: awsdocs/aws-doc-sdk-examples-tools@2024.49.1 + uses: awsdocs/aws-doc-sdk-examples-tools@2024.50.2 with: doc_gen_only: "False" strict_titles: "True" diff --git a/.tools/readmes/config.py b/.tools/readmes/config.py index 832b5c46ff9..0794176d9ac 100644 --- a/.tools/readmes/config.py +++ b/.tools/readmes/config.py @@ -27,6 +27,7 @@ "&kms-key;": "KMS key", "&kms-keys;": "KMS keys", "&S3long;": "Amazon Simple Storage Service", + "&S3only;": "S3", "&SLN;": "Amazon States Language", } language = { diff --git a/.tools/readmes/includes/code_examples.jinja2 b/.tools/readmes/includes/code_examples.jinja2 index 16e9f5ed88a..6c512bd54fa 100644 --- a/.tools/readmes/includes/code_examples.jinja2 +++ b/.tools/readmes/includes/code_examples.jinja2 @@ -33,7 +33,14 @@ functions within the same service. {{ macs.list_examples(scenarios) }} {% endif %} {% for cat, cat_examples in custom_cats.items() %} +{% set cat_info = categories.get(cat) %} +{% if cat_info %} +### {{ cat_info.display }} +{% if cat_info.description %}_{{ cat_info.display }}_ {{ cat_info.description }}{% endif %} + +{% else %} ### {{ cat }} +{% endif %} {{ macs.list_examples(cat_examples) }} {% endfor %} diff --git a/.tools/readmes/render.py b/.tools/readmes/render.py index d99270fbd58..66b6252fb9a 100644 --- a/.tools/readmes/render.py +++ b/.tools/readmes/render.py @@ -13,6 +13,7 @@ from typing import Dict, List, Tuple import config +from aws_doc_sdk_examples_tools.categories import Category from aws_doc_sdk_examples_tools.entities import expand_all_entities from aws_doc_sdk_examples_tools.metadata import Example from aws_doc_sdk_examples_tools.sdks import Sdk @@ -128,6 +129,7 @@ def _transform_examples( "api": api, "category": pre.category, } + self._apply_defaults_and_overrides(action) post_examples.append(action) return sorted(post_examples, key=itemgetter(sort_key)) @@ -153,6 +155,31 @@ def _find_files(self, example: Example, api: str, github: bool = False): return file, run_file + def _make_plain_text(self, s: str, example: Dict[str, str]) -> [str, None]: + """Work around strings being Go templates and including XML tags by brute forcing them away.""" + if s is None: + return s + return s.replace("", "")\ + .replace("", "")\ + .replace("{{.Action}}", example["api"])\ + .replace("{{.ServiceEntity.Short}}", self.scanner.doc_gen.services[self.scanner.svc_name].short) + + def _apply_defaults_and_overrides(self, example: Dict[str, str]): + ex_cat = "Actions" if example["category"] == "Api" else example["category"] + cat = self.scanner.doc_gen.categories.get(ex_cat, None) + if cat is not None: + if cat.overrides: + example["title"] = self._make_plain_text(cat.overrides.title, example) + example["title_abbrev"] = self._make_plain_text(cat.overrides.title_abbrev, example) + example["synopsis"] = self._make_plain_text(cat.overrides.synopsis, example) + elif cat.defaults: + if not example.get("title"): + example["title"] = self._make_plain_text(cat.defaults.title, example) + if not example.get("title_abbrev"): + example["title_abbrev"] = self._make_plain_text(cat.defaults.title_abbrev, example) + if not example.get("synopsis"): + example["synopsis"] = self._make_plain_text(cat.defaults.synopsis, example) + def _transform_hellos(self) -> List[Dict[str, str]]: examples = self._transform_examples(self.scanner.hellos) return examples @@ -160,15 +187,12 @@ def _transform_hellos(self) -> List[Dict[str, str]]: def _transform_actions(self) -> List[Dict[str, str]]: examples = self._transform_examples(self.scanner.actions, sort_key="api") for example in examples: - example["title_abbrev"] = example["api"] del example["api"] return examples def _transform_basics(self) -> List[Dict[str, str]]: examples = self._transform_examples(self.scanner.basics) for example in examples: - if not example["title_abbrev"]: - example["title_abbrev"] = config.basics_title_abbrev example["file"] = example["run_file"] del example["run_file"] del example["api"] @@ -196,7 +220,8 @@ def _transform_custom_categories(self) -> Dict[str, List[Dict[str, str]]]: post_cats[example["category"]].append(example) sorted_cats = {} - for key in sorted(post_cats.keys()): + for key in sorted(post_cats.keys(), + key=lambda x: self.scanner.doc_gen.categories.get(x, Category(x, x)).display): if len(post_cats[key]) == 0: del sorted_cats[key] else: @@ -295,6 +320,7 @@ def render(self) -> RenderStatus: lang_config=self.lang_config, sdk=sdk, service=svc, + categories=self.scanner.doc_gen.categories, hello=hello, actions=actions, basics=basics, diff --git a/dotnetv3/Glacier/README.md b/dotnetv3/Glacier/README.md index c78bb72d3bb..a3b6aa7fe34 100644 --- a/dotnetv3/Glacier/README.md +++ b/dotnetv3/Glacier/README.md @@ -31,7 +31,7 @@ For prerequisites, see the [README](../README.md#Prerequisites) in the `dotnetv3 ### Get started -- [Hello Amazon S3 Glacier](Actions/HelloGlacier.cs#L4) (`ListVaults`) +- [Hello S3 Glacier](Actions/HelloGlacier.cs#L4) (`ListVaults`) ### Single actions @@ -76,9 +76,9 @@ Alternatively, you can run the example from within your IDE. -#### Hello Amazon S3 Glacier +#### Hello S3 Glacier -This example shows you how to get started using Amazon S3 Glacier. +This example shows you how to get started using S3 Glacier. @@ -108,4 +108,4 @@ in the `dotnetv3` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/dotnetv3/MediaConvert/README.md b/dotnetv3/MediaConvert/README.md index 61e634dc610..f02a7fcd77e 100644 --- a/dotnetv3/MediaConvert/README.md +++ b/dotnetv3/MediaConvert/README.md @@ -83,7 +83,7 @@ The project includes the following settings in `settings.json`: #### Hello MediaConvert -This example shows you how to get started using AWS Elemental MediaConvert. +This example shows you how to get started using MediaConvert. @@ -113,4 +113,4 @@ in the `dotnetv3` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/gov2/bedrock-runtime/README.md b/gov2/bedrock-runtime/README.md index 348cb1de378..249b452f44f 100644 --- a/gov2/bedrock-runtime/README.md +++ b/gov2/bedrock-runtime/README.md @@ -31,7 +31,7 @@ For prerequisites, see the [README](../README.md#Prerequisites) in the `gov2` fo ### Get started -- [Hello Amazon Bedrock](hello/hello.go#L4) (`InvokeModel`) +- [Hello Amazon Bedrock Runtime](hello/hello.go#L4) (`InvokeModel`) ### Scenarios @@ -78,9 +78,9 @@ go run ./hello -region=eu-central-1 Be aware that not all regions may support Bedrock and its models yet. Verify service availability for your region [here](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). For available models per region, refer to the [Bedrock dashboard](https://console.aws.amazon.com/bedrock) in the AWS Management Console. -#### Hello Amazon Bedrock +#### Hello Amazon Bedrock Runtime -This example shows you how to get started using Amazon Bedrock. +This example shows you how to get started using Amazon Bedrock Runtime. ``` go run ./hello @@ -133,4 +133,4 @@ in the `gov2` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/gov2/cognito/README.md b/gov2/cognito/README.md index b49a96ff934..a56500564ae 100644 --- a/gov2/cognito/README.md +++ b/gov2/cognito/README.md @@ -31,7 +31,7 @@ For prerequisites, see the [README](../README.md#Prerequisites) in the `gov2` fo ### Get started -- [Hello Amazon Cognito](hello/hello.go#L4) (`ListUserPools`) +- [Hello Amazon Cognito Identity Provider](hello/hello.go#L4) (`ListUserPools`) ### Single actions @@ -69,9 +69,9 @@ functions within the same service. -#### Hello Amazon Cognito +#### Hello Amazon Cognito Identity Provider -This example shows you how to get started using Amazon Cognito. +This example shows you how to get started using Amazon Cognito Identity Provider. ``` go run ./hello @@ -162,4 +162,4 @@ in the `gov2` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/javascriptv3/example_code/bedrock-runtime/README.md b/javascriptv3/example_code/bedrock-runtime/README.md index 11856802302..beb3f1cef10 100644 --- a/javascriptv3/example_code/bedrock-runtime/README.md +++ b/javascriptv3/example_code/bedrock-runtime/README.md @@ -36,7 +36,7 @@ For prerequisites, see the [README](../../README.md#Prerequisites) in the `javas ### Get started -- [Hello Amazon Bedrock](hello.js) (`InvokeModel`) +- [Hello Amazon Bedrock Runtime](hello.js) (`InvokeModel`) ### Scenarios @@ -118,9 +118,9 @@ for that file. -#### Hello Amazon Bedrock +#### Hello Amazon Bedrock Runtime -This example shows you how to get started using Amazon Bedrock. +This example shows you how to get started using Amazon Bedrock Runtime. ```bash node ./hello.js @@ -165,4 +165,4 @@ in the `javascriptv3` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/javascriptv3/example_code/cognito-identity-provider/README.md b/javascriptv3/example_code/cognito-identity-provider/README.md index fa0787fde32..b0e4b8d1109 100644 --- a/javascriptv3/example_code/cognito-identity-provider/README.md +++ b/javascriptv3/example_code/cognito-identity-provider/README.md @@ -31,7 +31,7 @@ For prerequisites, see the [README](../../README.md#Prerequisites) in the `javas ### Get started -- [Hello Amazon Cognito](hello.js#L6) (`ListUserPools`) +- [Hello Amazon Cognito Identity Provider](hello.js#L6) (`ListUserPools`) ### Single actions @@ -98,9 +98,9 @@ for that file. -#### Hello Amazon Cognito +#### Hello Amazon Cognito Identity Provider -This example shows you how to get started using Amazon Cognito. +This example shows you how to get started using Amazon Cognito Identity Provider. ```bash node ./hello.js @@ -164,4 +164,4 @@ in the `javascriptv3` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/javascriptv3/example_code/elastic-load-balancing-v2/README.md b/javascriptv3/example_code/elastic-load-balancing-v2/README.md index 5c92777d16d..587d457f8cb 100644 --- a/javascriptv3/example_code/elastic-load-balancing-v2/README.md +++ b/javascriptv3/example_code/elastic-load-balancing-v2/README.md @@ -31,7 +31,7 @@ For prerequisites, see the [README](../../README.md#Prerequisites) in the `javas ### Get started -- [Hello Elastic Load Balancing](hello.js) (`DescribeLoadBalancers`) +- [Hello Elastic Load Balancing - Version 2](hello.js) (`DescribeLoadBalancers`) ### Single actions @@ -91,9 +91,9 @@ for that file. -#### Hello Elastic Load Balancing +#### Hello Elastic Load Balancing - Version 2 -This example shows you how to get started using Elastic Load Balancing. +This example shows you how to get started using Elastic Load Balancing - Version 2. ```bash node ./hello.js @@ -144,4 +144,4 @@ in the `javascriptv3` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/javav2/example_code/kms/README.md b/javav2/example_code/kms/README.md index 1fff4175d19..c20ad22abbe 100644 --- a/javav2/example_code/kms/README.md +++ b/javav2/example_code/kms/README.md @@ -77,7 +77,7 @@ Code excerpts that show you how to call individual service functions. #### Hello AWS KMS -This example shows you how to get started using AWS Key Management Service (AWS KMS). +This example shows you how to get started using AWS KMS. #### Learn the basics @@ -126,4 +126,4 @@ in the `javav2` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket/README.md b/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket/README.md index 46b7961bcd8..f372b6f3142 100644 --- a/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket/README.md +++ b/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket/README.md @@ -31,7 +31,7 @@ For prerequisites, see the [README](../../../../../../../../../README.md#Prerequ ### Get started -- [Hello Amazon S3 directory buckets](HelloS3DirectoryBuckets.java#L4) (`CreateBucket`) +- [Hello S3 Directory Buckets](HelloS3DirectoryBuckets.java#L4) (`CreateBucket`) ### Single actions @@ -83,9 +83,9 @@ functions within the same service. -#### Hello Amazon S3 directory buckets +#### Hello S3 Directory Buckets -This example shows you how to get started using Amazon S3 directory buckets. +This example shows you how to get started using S3 Directory Buckets. @@ -127,4 +127,4 @@ in the `javav2` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/php/example_code/kms/README.md b/php/example_code/kms/README.md index dfc43db2078..5538cc38bd3 100644 --- a/php/example_code/kms/README.md +++ b/php/example_code/kms/README.md @@ -77,7 +77,7 @@ Code excerpts that show you how to call individual service functions. #### Hello AWS KMS -This example shows you how to get started using AWS Key Management Service (AWS KMS). +This example shows you how to get started using AWS KMS. #### Learn the basics @@ -126,4 +126,4 @@ in the `php` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/python/example_code/cognito/README.md b/python/example_code/cognito/README.md index 6f0661addb5..6919d9296ae 100644 --- a/python/example_code/cognito/README.md +++ b/python/example_code/cognito/README.md @@ -36,7 +36,7 @@ python -m pip install -r requirements.txt ### Get started -- [Hello Amazon Cognito](hello/hello_cognito.py#L4) (`ListUserPools`) +- [Hello Amazon Cognito Identity Provider](hello/hello_cognito.py#L4) (`ListUserPools`) ### Single actions @@ -75,9 +75,9 @@ functions within the same service. -#### Hello Amazon Cognito +#### Hello Amazon Cognito Identity Provider -This example shows you how to get started using Amazon Cognito. +This example shows you how to get started using Amazon Cognito Identity Provider. ``` python hello/hello_cognito.py @@ -140,4 +140,4 @@ in the `python` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/python/example_code/elastic-load-balancing/README.md b/python/example_code/elastic-load-balancing/README.md index 452902b1321..693d4b4ee14 100644 --- a/python/example_code/elastic-load-balancing/README.md +++ b/python/example_code/elastic-load-balancing/README.md @@ -40,7 +40,7 @@ python -m pip install -r requirements.txt ### Get started -- [Hello Elastic Load Balancing](hello.py#L4) (`DescribeLoadBalancers`) +- [Hello Elastic Load Balancing - Version 2](hello.py#L4) (`DescribeLoadBalancers`) ### Single actions @@ -74,9 +74,9 @@ functions within the same service. -#### Hello Elastic Load Balancing +#### Hello Elastic Load Balancing - Version 2 -This example shows you how to get started using Elastic Load Balancing. +This example shows you how to get started using Elastic Load Balancing - Version 2. ``` python hello.py @@ -135,4 +135,4 @@ in the `python` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0 diff --git a/ruby/example_code/cognito/README.md b/ruby/example_code/cognito/README.md index 7576c3359c9..d8e6ca91aa4 100644 --- a/ruby/example_code/cognito/README.md +++ b/ruby/example_code/cognito/README.md @@ -31,7 +31,7 @@ For prerequisites, see the [README](../../README.md#Prerequisites) in the `ruby` ### Get started -- [Hello Amazon Cognito](hello/hello_cognito.rb#L4) (`ListUserPools`) +- [Hello Amazon Cognito Identity Provider](hello/hello_cognito.rb#L4) (`ListUserPools`) @@ -45,9 +45,9 @@ For prerequisites, see the [README](../../README.md#Prerequisites) in the `ruby` -#### Hello Amazon Cognito +#### Hello Amazon Cognito Identity Provider -This example shows you how to get started using Amazon Cognito. +This example shows you how to get started using Amazon Cognito Identity Provider. ``` ruby hello/hello_cognito.rb @@ -80,4 +80,4 @@ in the `ruby` folder. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -SPDX-License-Identifier: Apache-2.0 \ No newline at end of file +SPDX-License-Identifier: Apache-2.0