A bunch of templates translated to etmpl

.doc_gen/templates/zonbook/utility/hello.py

@@ -0,0 +1,20 @@
+def hello(example_sets, example_suffix="tablist", prefix, isSnapshot):
+    hello = example_sets['Hello']
+    if not hello.Examples:
+        return block()
+    example_prefix = f"prefix_" if prefix else ""
+    include_docs = "" if isSnapshot else "file://AWSShared/code-samples/docs/"
+    return block(
+        para(emphasis(role="bold", "Get started")),
+        block(
+            collapsible(_props={"expand-section"="_collapse_all_"}, *[
+                section(id=f"{example_prefix}example_{ex.ExampleId}_section",
+                        info(
+                            title(id=f"{example_prefix}example_{ex.ExampleId}_section.title", ex.Title),
+                            titleabbrev(id=f"{example_prefix}example_{ex.ExampleId}_section.titleabbrev",ex.TitleAbbrev),
+                            abstract(para(ex.Title))),
+                    xi_include(href=f"{include_docs}{ex.ExampleId}_desc.xml"),
+                    xi_include(href=f"{include_docs}{ex.ExampleId}_{example_suffix}.xml"),)
+            ] for ex in hello.Examples)
+        )
+    )

.doc_gen/templates/zonbook/utility/notes.py

@@ -0,0 +1,35 @@
+def note_example_types(actions, scenarios, crosses):
+    blocks = []
+    if actions:
+        blocks.append(
+            para(
+                emphasis("Actions"),
+                " are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios and cross-service examples.",
+            )
+        )
+    if scenarios:
+        blocks.append(
+            para(
+                emphasis("Scenarios"),
+                " are code examples that show you how to accomplish a specific task by calling multiple functions within the same service.",
+            )
+        )
+    if crosses:
+        blocks.append(
+            para(
+                emphasis("Cross-service examples"),
+                " are sample applications that work across multiple &AWS-services;.",
+            )
+        )
+    return blocks
+
+
+def note_complete_list():
+    return para(
+        "For a complete list of &AWS; SDK developer guides and code examples, see ",
+        xref(
+            linkend="sdk-general-information-section",
+            endterm="sdk-general-information-section.title",
+        ),
+        ". This topic also includes information about getting started and details about previous SDK versions.",
+    )

.doc_gen/templates/zonbook/utility/prologue.py

@@ -0,0 +1,20 @@
+def prologue(isSnapshot):
+    prologue_xml_literal = """
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file://zonbook/docbookx.dtd"[
+    <!ENTITY % xinclude SYSTEM "file://AWSShared/common/xinclude.mod">
+    %xinclude;
+"""
+    if isSnapshot:
+        prologue_xml_literal += (
+            """<!ENTITY % phrases-code-examples SYSTEM "phrases-code-examples.ent">"""
+        )
+    else:
+        prologue_xml_literal += """<!ENTITY % phrases-code-examples SYSTEM "file://AWSShared/code-samples/docs/phrases-code-examples.ent">"""
+    prologue_xml_literal += """
+    %phrases-code-examples;
+    <!ENTITY % phrases-shared SYSTEM "file://AWSShared/common/phrases-shared.ent">
+    %phrases-shared;
+]>
+"""
+    return prologue_xml_literal

.tools/readmes/includes/code_examples.py

@@ -0,0 +1,56 @@
+from typing import Optional
+
+from macros import list_examples, commented_block
+from prerequisites import prerequisites
+
+
+def example_block(title: str, description: Optional[str], examples):
+    return block(h3(title), description, list_examples(examples))
+
+
+def code_examples(
+    hello,
+    actions,
+    scenarios,
+    custom_categories: dict[str, list],
+    crosses,
+    customs: dict[str, str],
+):
+    blocks = []
+    if hello:
+        blocks.append(example_block("Get started", None, hello))
+    if actions:
+        blocks.append(
+            example_block(
+                "Single actions",
+                "Code excerpts that show you how to call individual service functions.",
+                actions,
+            )
+        )
+    if scenarios:
+        blocks.append(
+            example_block(
+                "Scenarios",
+                "Code examples that show you how to accomplish a specific task by calling multiple functions within the same service. ",
+                scenarios,
+            )
+        )
+
+    for cat, examples in custom_categories.items():
+        blocks.append(example_block(cat, None, examples))
+
+    if crosses:
+        blocks.append(
+            example_block(
+                "Cross-service examples",
+                "Sample applications that work across multiple AWS services.",
+                crosses,
+            )
+        )
+
+    return block(
+        h2("Code Examples"),
+        prerequisites(),
+        *blocks,
+        commented_block("custom.examples", customs["examples"])
+    )

.tools/readmes/includes/copyright.py

@@ -0,0 +1,9 @@
+_COPYRIGHT = """---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0"""
+
+
+def copyright():
+    return text(_COPYRIGHT)

.tools/readmes/includes/important.py

@@ -0,0 +1,34 @@
+from macros import commented_block
+
+
+def important(customs: dict[str, str]):
+    return block(
+        h2("⚠ Important"),
+        unordered_list(
+            item(
+                "Running this code might result in charges to your AWS account. For more details, see ",
+                link(href="https://aws.amazon.com/pricing/", title="AWS Pricing"),
+                " and ",
+                link(title="Free Tier", href="https://aws.amazon.com/free/"),
+                ".",
+            ),
+            item("Running the tests might result in charges to your AWS account."),
+            item(
+                "We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see ",
+                link(
+                    title="Grant least privilege",
+                    title="https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege",
+                ),
+                ".",
+            ),
+            item(
+                "This code is not tested in every AWS Region. For more information, see ",
+                link(
+                    title="AWS Regional Services",
+                    href="https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services",
+                ),
+                ".",
+            ),
+        ),
+        commented_block("custom.important", customs["important"]),
+    )

.tools/readmes/includes/macros.py

@@ -0,0 +1,12 @@
+def commented_block(name: str, blurb: str):
+    return block(comment(f"{name}.start"), blurb, comment(f"{name}.end"))
+
+def list_example(example):
+    file_link = link(title=example['title_abbrev'], href=example['file'])
+    api_ = example['api'] or ""
+    if api_:
+        api_ = f" ({api_})"
+    return item(file_link, api_)
+
+def list_examples(examples):
+    unordered_list(*[item(example)] for example in examples)

.tools/readmes/includes/overview.py

@@ -0,0 +1,9 @@
+from macros import commented_block
+
+def overview(sdk, service, customs):
+    return block(
+        h2("Overview"),
+        para(f"Shows how to use the {sdk['long']} to work with {service['long']}."),
+        commented_block("custom.overview", customs['overview']),
+        para(emphasis(f"{service['short']} {service["blurb"]}"))
+    )