Add fields to sdk and category to let authors control display.

Author: Laren-AWS

aws_doc_sdk_examples_tools/categories.py

@@ -56,6 +56,25 @@ def from_yaml(cls, yaml: Dict[str, str] | None) -> Optional[TitleInfo]:
         )
 
 
+@dataclass
+class Prefix:
+    one: Optional[str]
+    many: Optional[str]
+
+    @classmethod
+    def from_yaml(cls, yaml: Optional[Dict[str, str]]) -> Optional[Prefix]:
+        if yaml is None:
+            return None
+
+        one = yaml.get("one")
+        many = yaml.get("many")
+
+        return cls(
+            one=one,
+            many=many,
+        )
+
+
 @dataclass
 class CategoryWithNoDisplayError(metadata_errors.MetadataError):
     def message(self):
@@ -72,6 +91,8 @@ class Category:
     defaults: Optional[TitleInfo] = field(default=None)
     overrides: Optional[TitleInfo] = field(default=None)
     description: Optional[str] = field(default=None)
+    synopsis_prefix: Optional[Prefix] = field(default=None)
+    more_info: Optional[str] = field(default=None)
 
     def evaluate(
         self,
@@ -103,6 +124,8 @@ def from_yaml(
         defaults = TitleInfo.from_yaml(yaml.get("defaults"))
         overrides = TitleInfo.from_yaml(yaml.get("overrides"))
         description = yaml.get("description")
+        synopsis_prefix = Prefix.from_yaml(yaml.get("synopsis_prefix"))
+        more_info = yaml.get("more_info")
 
         return (
             cls(
@@ -111,6 +134,8 @@ def from_yaml(
                 defaults=defaults,
                 overrides=overrides,
                 description=description,
+                synopsis_prefix=synopsis_prefix,
+                more_info=more_info,
             ),
             errors,
         )

aws_doc_sdk_examples_tools/categories_test.py

@@ -11,6 +11,7 @@
     parse,
     Category,
     TitleInfo,
+    Prefix,
 )
 
 
@@ -65,6 +66,8 @@ def test_categories():
             key="TributaryLite",
             display="Tea light",
             description="light your way.",
+            synopsis_prefix=Prefix(one="Tea light is", many="Tea lights are"),
+            more_info="This is more tea light info.",
         ),
     }
 

aws_doc_sdk_examples_tools/config/sdks_schema.yaml

@@ -3,17 +3,20 @@
 map(include('sdk'), key=enum('Bash', 'C++', 'CLI', 'Go', 'Java', 'JavaScript', 'Kotlin', '.NET', 'PHP', 'PowerShell', 'Python', 'Ruby', 'Rust', 'SAP ABAP', 'Swift'))
 ---
 sdk:
+  display: str(required=False)
   property: include('syntax_enum')
   syntax: include('syntax_enum', required=False)
   sdk: map(include('version'), key=int(min=1))
   guide: include('entity_regex')
+  is_pseudo_sdk: bool(required=False)
 
 version:
   long: include('entity_with_version_regex')
   short: include('entity_with_version_regex')
   expanded:
     long: str(upper_start=True, end_punc=False, check_aws=False)
     short: str(upper_start=True, end_punc=False, check_aws=False)
+  suppress_version_heading: bool(required=False)
   guide: str()
   caveat: str(required=False, upper_start=True, end_punc=True)
   bookmark: str(required=False)

aws_doc_sdk_examples_tools/doc_gen_cli_test.py

@@ -60,9 +60,11 @@ def mock_doc_gen(mock_example):
     doc_gen.sdks = {
         "JavaScript": Sdk(
             name="JavaScript",
+            display="JavaScript",
             versions=[SdkVersion(version=3, long="&JS;", short="&JSlong")],
             guide="",
             property="javascript",
+            is_pseudo_sdk=False,
         )
     }
     doc_gen.examples = {"ex": mock_example}

aws_doc_sdk_examples_tools/doc_gen_test.py

@@ -26,7 +26,14 @@
                 root=Path("/a"),
                 errors=MetadataErrors(),
                 sdks={
-                    "a": Sdk(name="a", guide="guide_a", property="a_prop", versions=[])
+                    "a": Sdk(
+                        name="a",
+                        display="aa",
+                        guide="guide_a",
+                        property="a_prop",
+                        versions=[],
+                        is_pseudo_sdk=False,
+                    ),
                 },
                 services={
                     "x": Service(long="AWS X", short="X", sort="aws x", version=1)
@@ -36,7 +43,14 @@
                 root=Path("/b"),
                 errors=MetadataErrors(),
                 sdks={
-                    "b": Sdk(name="b", guide="guide_b", property="b_prop", versions=[])
+                    "b": Sdk(
+                        name="b",
+                        display="bb",
+                        guide="guide_b",
+                        property="b_prop",
+                        versions=[],
+                        is_pseudo_sdk=False,
+                    ),
                 },
                 services={
                     "y": Service(long="AWS Y", short="Y", sort="aws y", version=1)
@@ -46,8 +60,22 @@
                 root=Path("/a"),
                 errors=MetadataErrors(),
                 sdks={
-                    "a": Sdk(name="a", guide="guide_a", property="a_prop", versions=[]),
-                    "b": Sdk(name="b", guide="guide_b", property="b_prop", versions=[]),
+                    "a": Sdk(
+                        name="a",
+                        display="aa",
+                        guide="guide_a",
+                        property="a_prop",
+                        versions=[],
+                        is_pseudo_sdk=False,
+                    ),
+                    "b": Sdk(
+                        name="b",
+                        display="bb",
+                        guide="guide_b",
+                        property="b_prop",
+                        versions=[],
+                        is_pseudo_sdk=False,
+                    ),
                 },
                 services={
                     "x": Service(long="AWS X", short="X", sort="aws x", version=1),
@@ -91,9 +119,11 @@ def sample_doc_gen() -> DocGen:
         sdks={
             "python": Sdk(
                 name="python",
+                display="Python",
                 versions=[SdkVersion(version=1, long="&PYLong;", short="&PYShort;")],
                 guide="Python Guide",
                 property="python",
+                is_pseudo_sdk=False,
             )
         },
         services={
@@ -167,7 +197,9 @@ def test_doc_gen_encoder(sample_doc_gen: DocGen):
     assert "sdks" in decoded
     assert "python" in decoded["sdks"]
     assert decoded["sdks"]["python"]["name"] == "python"
+    assert decoded["sdks"]["python"]["display"] == "Python"
     assert decoded["sdks"]["python"]["guide"] == "Python Guide"
+    assert decoded["sdks"]["python"]["is_pseudo_sdk"] == False
     assert decoded["sdks"]["python"]["versions"][0]["version"] == 1
     assert decoded["sdks"]["python"]["versions"][0]["long"] == "&PYLong;"
 

aws_doc_sdk_examples_tools/metadata_test.py

@@ -89,10 +89,38 @@ def load(
     ),
 }
 SDKS = {
-    "C++": Sdk(name="C++", versions=[], guide="", property="cpp"),
-    "Java": Sdk(name="Java", versions=[], guide="", property="java"),
-    "JavaScript": Sdk(name="JavaScript", versions=[], guide="", property="javascript"),
-    "PHP": Sdk(name="PHP", versions=[], guide="", property="php"),
+    "C++": Sdk(
+        name="C++",
+        display="C++",
+        versions=[],
+        guide="",
+        property="cpp",
+        is_pseudo_sdk=False,
+    ),
+    "Java": Sdk(
+        name="Java",
+        display="Java",
+        versions=[],
+        guide="",
+        property="java",
+        is_pseudo_sdk=False,
+    ),
+    "JavaScript": Sdk(
+        name="JavaScript",
+        display="JavaScript",
+        versions=[],
+        guide="",
+        property="javascript",
+        is_pseudo_sdk=False,
+    ),
+    "PHP": Sdk(
+        name="PHP",
+        display="PHP",
+        versions=[],
+        guide="",
+        property="php",
+        is_pseudo_sdk=False,
+    ),
 }
 STANDARD_CATS = ["Api"]
 DOC_GEN = DocGen(

aws_doc_sdk_examples_tools/sdks.py

@@ -58,6 +58,7 @@ class SdkVersion:
     long: str
     short: str
     expanded: Optional[SdkVersionExpanded] = field(default=None)
+    suppress_version_heading: bool = field(default=False)
     guide: Optional[str] = field(default=None)
     api_ref: Optional[SdkApiRef] = field(default=None)
     caveat: Optional[str] = field(default=None)
@@ -71,6 +72,7 @@ def from_yaml(
         errors = MetadataErrors()
         long = check_mapping(yaml.get("long"), "long", strict)
         short = check_mapping(yaml.get("short"), "short", strict)
+        suppress_version_heading = yaml.get("suppress_version_heading", False)
         guide = yaml.get("guide")
         caveat = yaml.get("caveat")
         bookmark = yaml.get("bookmark")
@@ -113,6 +115,7 @@ def from_yaml(
                 long=long,
                 short=short,
                 expanded=expanded,
+                suppress_version_heading=suppress_version_heading,
                 guide=guide,
                 api_ref=api_ref,
                 caveat=caveat,
@@ -132,9 +135,11 @@ def message(self):
 @dataclass
 class Sdk:
     name: str
+    display: str
     versions: List[SdkVersion]
     guide: str
     property: str
+    is_pseudo_sdk: bool
 
     def validate(self, errors: MetadataErrors):
         if len(self.versions) == 0:
@@ -145,8 +150,10 @@ def from_yaml(
         cls, name: str, yaml: Dict[str, Any], strict: bool
     ) -> tuple[Sdk, MetadataErrors]:
         errors = MetadataErrors()
+        display = yaml.get("display", name)
         property = yaml.get("property", "")
         guide = check_mapping(yaml.get("guide"), "guide")
+        is_pseudo_sdk = yaml.get("is_pseudo_sdk", False)
         if isinstance(guide, MetadataParseError):
             errors.append(guide)
             guide = ""
@@ -161,7 +168,17 @@ def from_yaml(
             versions.append(sdk_version)
             errors.extend(errs)
 
-        return cls(name=name, versions=versions, guide=guide, property=property), errors
+        return (
+            cls(
+                name=name,
+                display=display,
+                versions=versions,
+                guide=guide,
+                property=property,
+                is_pseudo_sdk=is_pseudo_sdk,
+            ),
+            errors,
+        )
 
 
 def parse(