Services sdk_id updates. (#166)

Adds an sdk_id value for services, and includes that value in the example_meta.json file. The sdk_id is used to map a service to its Smithy model, for use when auto-generating links to code examples within API Ref documentation.

Author: rlhagerm

aws_doc_sdk_examples_tools/config/services.yaml

@@ -6,6 +6,7 @@ service:
   long: str()
   short: str()
   sort: regex('^[^&]\\w', name='non-entity')
+  sdk_id: str()
   chapter_override: include('chapter_override', required=False)
   expanded:
     long: str(upper_start=True, end_punc=False, check_aws=False)

aws_doc_sdk_examples_tools/config/services_schema.yaml

@@ -288,6 +288,7 @@ def safe_split_id(ex_id: str) -> Tuple[str, str]:
                 action = id_action
             if service_id in self.services:
                 service_name = self.services[service_id].short
+                example.service_sdk_id = self.services[service_id].sdk_id
             else:
                 service_name = service_id
             example.fill_display_fields(self.categories, service_name, action)

aws_doc_sdk_examples_tools/doc_gen.py

@@ -55,6 +55,7 @@ def mock_doc_gen(mock_example):
             short="&AHI;",
             sort="HealthImaging",
             version="medical-imaging-2023-07-19",
+            sdk_id="Medical Imaging",
         )
     }
     doc_gen.sdks = {

aws_doc_sdk_examples_tools/doc_gen_cli_test.py

@@ -36,7 +36,9 @@
                     ),
                 },
                 services={
-                    "x": Service(long="AWS X", short="X", sort="aws x", version=1)
+                    "x": Service(
+                        long="AWS X", short="X", sort="aws x", version=1, sdk_id="AWSx"
+                    )
                 },
             ),
             DocGen(
@@ -53,7 +55,9 @@
                     ),
                 },
                 services={
-                    "y": Service(long="AWS Y", short="Y", sort="aws y", version=1)
+                    "y": Service(
+                        long="AWS Y", short="Y", sort="aws y", version=1, sdk_id="AWSy"
+                    )
                 },
             ),
             DocGen(
@@ -78,8 +82,12 @@
                     ),
                 },
                 services={
-                    "x": Service(long="AWS X", short="X", sort="aws x", version=1),
-                    "y": Service(long="AWS Y", short="Y", sort="aws y", version=1),
+                    "x": Service(
+                        long="AWS X", short="X", sort="aws x", version=1, sdk_id="AWSx"
+                    ),
+                    "y": Service(
+                        long="AWS Y", short="Y", sort="aws y", version=1, sdk_id="AWSy"
+                    ),
                 },
             ),
         )
@@ -135,6 +143,7 @@ def sample_doc_gen() -> DocGen:
                 ),
                 sort="Amazon S3",
                 version="2006-03-01",
+                sdk_id="S3",
             )
         },
         snippets={
@@ -152,6 +161,7 @@ def sample_doc_gen() -> DocGen:
                 "s3_PutObject",
                 file=Path("filea.txt"),
                 languages={},
+                service_sdk_id="S3",
                 services={"s3": set(["PutObject"])},
             )
         },
@@ -244,6 +254,7 @@ def test_doc_gen_encoder(sample_doc_gen: DocGen):
             "id": "s3_PutObject",
             "languages": {},
             "service_main": None,
+            "service_sdk_id": "S3",
             "services": {
                 "s3": {
                     "__set__": [

aws_doc_sdk_examples_tools/doc_gen_test.py

@@ -154,6 +154,8 @@ class Example:
     # TODO document service_main and services. Not to be used by tributaries. Part of Cross Service.
     # List of services used by the examples. Lines up with those in services.yaml.
     service_main: Optional[str] = field(default=None)
+    # Main service sdk_id. Matches Smithy model svc_id in services.yaml.
+    service_sdk_id: Optional[str] = field(default="")
     services: Dict[str, Set[str]] = field(default_factory=dict)
     # HTML file names corresponding to the documentation pages in the Code Library
     doc_filenames: Optional[DocFilenames] = field(default=None)

aws_doc_sdk_examples_tools/metadata.py

@@ -52,6 +52,7 @@ def load(
         ),
         sort="api-gateway",
         version=1,
+        sdk_id="apigateway",
     ),
     "medical-imaging": Service(
         long="&AHIlong;",
@@ -61,6 +62,7 @@ def load(
         ),
         sort="HealthImaging",
         version=1,
+        sdk_id="Medical Imaging",
     ),
     "sqs": Service(
         long="&SQSlong;",
@@ -70,6 +72,7 @@ def load(
         ),
         sort="sqs",
         version=1,
+        sdk_id="SQS",
     ),
     "s3": Service(
         long="&S3long;",
@@ -79,13 +82,15 @@ def load(
         ),
         sort="s3",
         version=1,
+        sdk_id="S3",
     ),
     "autogluon": Service(
         long="AutoGluon Test",
         short="AG Test",
         expanded=ServiceExpanded(long="AutoGluon Test", short="AutoGluon Test"),
         sort="autogluon",
         version=1,
+        sdk_id="",
     ),
 }
 SDKS = {
@@ -1025,8 +1030,12 @@ def test_no_duplicate_title_abbrev():
             ),
         },
         services={
-            "svc": Service(long="Service", short="svc", version="1", sort="svc"),
-            "cvs": Service(long="CVS", short="cvs", version="2", sort="cvs"),
+            "svc": Service(
+                long="Service", short="svc", version="1", sort="svc", sdk_id="SVC"
+            ),
+            "cvs": Service(
+                long="CVS", short="cvs", version="2", sort="cvs", sdk_id="CVS"
+            ),
         },
     )
     doc_gen.validate()

aws_doc_sdk_examples_tools/metadata_test.py

@@ -26,6 +26,7 @@ class Service:
     long: str
     short: str
     sort: str
+    sdk_id: str
     version: Union[int, str]
     expanded: Optional[ServiceExpanded] = field(default=None)
     api_ref: Optional[str] = field(default=None)
@@ -50,6 +51,7 @@ def from_yaml(
         sort = yaml.get("sort")
         version = yaml.get("version")
         api_ref = yaml.get("api_ref")
+        sdk_id = yaml.get("sdk_id")
 
         if isinstance(long, metadata_errors.MetadataParseError):
             errors.append(long)
@@ -75,6 +77,9 @@ def from_yaml(
             version = "0"
         if api_ref is None:
             errors.append(metadata_errors.MissingField(field="api_ref"))
+        if sdk_id is None:
+            errors.append(metadata_errors.MissingField(field="sdk_id"))
+            sdk_id = ""
 
         blurb = yaml.get("blurb")
         caveat = yaml.get("caveat")
@@ -101,6 +106,7 @@ def from_yaml(
             cls(
                 long=long,
                 short=short,
+                sdk_id=sdk_id,
                 expanded=expanded,
                 sort=sort,
                 api_ref=api_ref,

aws_doc_sdk_examples_tools/services.py

@@ -66,6 +66,7 @@ def test_services():
     assert examples == {
         "s3": Service(
             short="&S3;",
+            sdk_id="S3",
             expanded=ServiceExpanded(
                 long="Amazon Simple Storage Service (Amazon S3)", short="Amazon S3"
             ),
@@ -83,6 +84,7 @@ def test_services():
         "medical-imaging": Service(
             short="&AHI;",
             long="&AHIlong;",
+            sdk_id="Medical Imaging",
             expanded=ServiceExpanded(
                 long="AWS HealthImaging",
                 short="HealthImaging",
@@ -93,6 +95,7 @@ def test_services():
         "sqs": Service(
             short="&SQS;",
             long="&SQSlong;",
+            sdk_id="SQS",
             expanded=ServiceExpanded(
                 long="Amazon Simple Queue Service (Amazon SQS)", short="Amazon SQS"
             ),
@@ -106,6 +109,7 @@ def test_services():
         "textract": Service(
             short="&TEXTRACT;",
             long="&TEXTRACTlong;",
+            sdk_id="Textract",
             expanded=ServiceExpanded(long="Amazon Textract", short="Amazon Textract"),
             sort="Textract",
             tags={"product_categories": set(["Category 1"])},

aws_doc_sdk_examples_tools/services_test.py

@@ -4,4 +4,5 @@ medical-imaging:
   expanded:
     long: AWS HealthImaging
     short: HealthImaging
+  sdk_id: Medical Imaging
   sort: HealthImaging