Tools & meta: add complex categories feature, update tools release, update READMEs (#7156)

Author: Laren-AWS

.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"

.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 = {

.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 %}

.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,22 +155,44 @@ 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("<code>", "")\
+            .replace("</code>", "")\
+            .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
 
     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,

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.
 <!--custom.instructions.start-->
 <!--custom.instructions.end-->
 
-#### 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
+SPDX-License-Identifier: Apache-2.0

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
+SPDX-License-Identifier: Apache-2.0

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.
 <!--custom.instructions.end-->
 
-#### 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
+SPDX-License-Identifier: Apache-2.0

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.
 <!--custom.instructions.start-->
 <!--custom.instructions.end-->
 
-#### 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
+SPDX-License-Identifier: Apache-2.0

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.
 <!--custom.instructions.start-->
 <!--custom.instructions.end-->
 
-#### 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
+SPDX-License-Identifier: Apache-2.0

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.
 <!--custom.instructions.start-->
 <!--custom.instructions.end-->
 
-#### 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
+SPDX-License-Identifier: Apache-2.0

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.
 <!--custom.instructions.start-->
 <!--custom.instructions.end-->
 
-#### 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
+SPDX-License-Identifier: Apache-2.0

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
+SPDX-License-Identifier: Apache-2.0

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.
 <!--custom.instructions.start-->
 <!--custom.instructions.end-->
 
-#### 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
+SPDX-License-Identifier: Apache-2.0

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
+SPDX-License-Identifier: Apache-2.0

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.
 <!--custom.instructions.start-->
 <!--custom.instructions.end-->
 
-#### 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
+SPDX-License-Identifier: Apache-2.0