diff --git a/.doc_gen/templates/zonbook/utility/hello.py b/.doc_gen/templates/zonbook/utility/hello.py new file mode 100644 index 00000000000..27cd55d0324 --- /dev/null +++ b/.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) + ) + ) \ No newline at end of file diff --git a/.doc_gen/templates/zonbook/utility/hello.xml b/.doc_gen/templates/zonbook/utility/hello.xml deleted file mode 100644 index 6dc19266164..00000000000 --- a/.doc_gen/templates/zonbook/utility/hello.xml +++ /dev/null @@ -1,37 +0,0 @@ -{{- define "hello"}} -{{- $example_sets := index . 0}} -{{- $hello := index $example_sets "Hello"}} -{{- $example_suffix := index . 1}} -{{- if not $example_suffix}} - {{- $example_suffix = "tablist"}} -{{- end}} -{{- $prefix := index . 2}} -{{- $example_prefix := ""}} -{{- if $prefix}} - {{- $example_prefix = printf "%s_" $prefix}} -{{- end}} -{{- $include_docs := "file://AWSShared/code-samples/docs/"}} -{{- if isSnapshot}} - {{- $include_docs = ""}} -{{- end}} -{{- if $hello.Examples}} -Get started - - - {{- range $hello.Examples}} -
- - {{.Title}} - {{.TitleAbbrev}} - - {{.Title}} - - - - -
- {{- end}} - - -{{- end}} -{{- end}} \ No newline at end of file diff --git a/.doc_gen/templates/zonbook/utility/notes.py b/.doc_gen/templates/zonbook/utility/notes.py new file mode 100644 index 00000000000..a0f508530c7 --- /dev/null +++ b/.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.", + ) diff --git a/.doc_gen/templates/zonbook/utility/notes.xml b/.doc_gen/templates/zonbook/utility/notes.xml deleted file mode 100644 index 6ffde7f012b..00000000000 --- a/.doc_gen/templates/zonbook/utility/notes.xml +++ /dev/null @@ -1,23 +0,0 @@ -{{- define "note_example_types"}} -{{- $actions := index . 0}} -{{- $scenarios := index . 1}} -{{- $crosses := index . 2}} -{{- if $actions}} -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. -{{- end}} -{{- if $scenarios}} -Scenarios are code examples that show you how to accomplish a specific task by - calling multiple functions within the same service. -{{- end}} -{{- if $crosses}} -Cross-service examples are sample applications that work across multiple &AWS-services;. -{{- end}} -{{- end}} - -{{- define "note_complete_list"}} -For a complete list of &AWS; SDK developer guides and code examples, see - . - This topic also includes information about getting started and details about previous SDK versions. -{{- end}} \ No newline at end of file diff --git a/.doc_gen/templates/zonbook/utility/prologue.py b/.doc_gen/templates/zonbook/utility/prologue.py new file mode 100644 index 00000000000..60d0cb71711 --- /dev/null +++ b/.doc_gen/templates/zonbook/utility/prologue.py @@ -0,0 +1,20 @@ +def prologue(isSnapshot): + prologue_xml_literal = """ + + + %xinclude; +""" + if isSnapshot: + prologue_xml_literal += ( + """""" + ) + else: + prologue_xml_literal += """""" + prologue_xml_literal += """ + %phrases-code-examples; + + %phrases-shared; +]> +""" + return prologue_xml_literal diff --git a/.doc_gen/templates/zonbook/utility/prologue.xml b/.doc_gen/templates/zonbook/utility/prologue.xml deleted file mode 100644 index 81fc3556cff..00000000000 --- a/.doc_gen/templates/zonbook/utility/prologue.xml +++ /dev/null @@ -1,14 +0,0 @@ -{{- define "prologue"}} - - %xinclude; -{{- if isSnapshot}} - -{{- else}} - -{{- end}} - %phrases-code-examples; - - %phrases-shared; -]> -{{- end}} \ No newline at end of file diff --git a/.tools/readmes/includes/__init__.py b/.tools/readmes/includes/__init__.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/.tools/readmes/includes/code_examples.jinja2 b/.tools/readmes/includes/code_examples.jinja2 deleted file mode 100644 index ff58f51e8e1..00000000000 --- a/.tools/readmes/includes/code_examples.jinja2 +++ /dev/null @@ -1,42 +0,0 @@ -## Code examples - -{% include 'includes/prerequisites.jinja2' %} - -{% if hello %} - -### Get started - -{{ macs.list_examples(hello) }} -{% endif %} -{% if actions %} - -### Single actions - -Code excerpts that show you how to call individual service functions. - -{{ macs.list_examples(actions) }} -{% endif %} -{% if scenarios %} -### Scenarios - -Code examples that show you how to accomplish a specific task by calling multiple -functions within the same service. - -{{ macs.list_examples(scenarios) }} -{% endif %} -{% for cat, cat_examples in custom_cats.items() %} -### {{ cat }} - -{{ macs.list_examples(cat_examples) }} -{% endfor %} -{% if crosses %} -### Cross-service examples - -Sample applications that work across multiple AWS services. - -{{ macs.list_examples(crosses) }} -{% endif %} - - -{{ customs['examples'] -}} - diff --git a/.tools/readmes/includes/code_examples.py b/.tools/readmes/includes/code_examples.py new file mode 100644 index 00000000000..2228beac668 --- /dev/null +++ b/.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"]) + ) diff --git a/.tools/readmes/includes/copyright.jinja2 b/.tools/readmes/includes/copyright.jinja2 deleted file mode 100644 index 8c2be61ee8a..00000000000 --- a/.tools/readmes/includes/copyright.jinja2 +++ /dev/null @@ -1,5 +0,0 @@ ---- - -Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. - -SPDX-License-Identifier: Apache-2.0 diff --git a/.tools/readmes/includes/copyright.py b/.tools/readmes/includes/copyright.py new file mode 100644 index 00000000000..e5c1166a052 --- /dev/null +++ b/.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) diff --git a/.tools/readmes/includes/important.jinja2 b/.tools/readmes/includes/important.jinja2 deleted file mode 100644 index 2dd79cdda65..00000000000 --- a/.tools/readmes/includes/important.jinja2 +++ /dev/null @@ -1,10 +0,0 @@ -## ⚠ Important - -* Running this code might result in charges to your AWS account. For more details, see [AWS Pricing](https://aws.amazon.com/pricing/) and [Free Tier](https://aws.amazon.com/free/). -* Running the tests might result in charges to your AWS account. -* 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 [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege). -* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services). - - -{{ customs['important'] -}} - diff --git a/.tools/readmes/includes/important.py b/.tools/readmes/includes/important.py new file mode 100644 index 00000000000..f6b696c0356 --- /dev/null +++ b/.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"]), + ) diff --git a/.tools/readmes/includes/macros.jinja2 b/.tools/readmes/includes/macros.jinja2 deleted file mode 100644 index 548cdba8834..00000000000 --- a/.tools/readmes/includes/macros.jinja2 +++ /dev/null @@ -1,6 +0,0 @@ -{% macro list_examples(examples) %} -{% for ex in examples %} -- [{{ ex['title_abbrev']}}]({{ex['file']}}){% if ex['api'] %} (`{{ex['api']}}`){% endif %} - -{% endfor %} -{% endmacro %} diff --git a/.tools/readmes/includes/macros.py b/.tools/readmes/includes/macros.py new file mode 100644 index 00000000000..61714f5d3db --- /dev/null +++ b/.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) \ No newline at end of file diff --git a/.tools/readmes/includes/overview.jinja2 b/.tools/readmes/includes/overview.jinja2 deleted file mode 100644 index 707f72283b8..00000000000 --- a/.tools/readmes/includes/overview.jinja2 +++ /dev/null @@ -1,9 +0,0 @@ -## Overview - -Shows how to use the {{sdk['long']}} to work with {{service['long']}}. - - -{{ customs['overview'] -}} - - -_{{ service['short'] }} {{ service['blurb'] }}_ diff --git a/.tools/readmes/includes/overview.py b/.tools/readmes/includes/overview.py new file mode 100644 index 00000000000..69f6da2745b --- /dev/null +++ b/.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"]}")) + ) diff --git a/.tools/readmes/includes/prerequisites.jinja2 b/.tools/readmes/includes/prerequisites.jinja2 deleted file mode 100644 index 3fbd97af16d..00000000000 --- a/.tools/readmes/includes/prerequisites.jinja2 +++ /dev/null @@ -1,31 +0,0 @@ -### Prerequisites - -{% if lang_config['name'] != 'C++' %} -For prerequisites, see the [README]({{lang_config['readme']}}#Prerequisites) in the `{{lang_config['base_folder']}}` folder. -{% endif %} - -{% if lang_config['name'] == 'Python' and lang_config['sdk_ver'] == 3 %} -Install the packages required by these examples by running the following in a virtual environment: - -``` -python -m pip install -r requirements.txt -``` -{% elif lang_config['name'] == 'C++' and lang_config['sdk_ver'] == 1 %} - -Before using the code examples, first complete the installation and setup steps -for [Getting started](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/getting-started.html) in the AWS SDK for -C++ Developer Guide. -This section covers how to get and build the SDK, and how to build your own code by using the SDK with a -sample Hello World-style application. - -Next, for information on code example structures and how to build and run the examples, see [Getting started with the AWS SDK for C++ code examples](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/getting-started-code-examples.html). - -{% endif %} -{% if service == 'bedrock' %} -> ⚠ You must request access to a model before you can use it. If you try to use the model (with the API or console) before you have requested access to it, you will receive an error message. For more information, see [Model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html). - -{% endif %} - - -{{ customs['prerequisites'] -}} - diff --git a/.tools/readmes/includes/prerequisites.py b/.tools/readmes/includes/prerequisites.py new file mode 100644 index 00000000000..11b6c345583 --- /dev/null +++ b/.tools/readmes/includes/prerequisites.py @@ -0,0 +1,65 @@ +from macros import commented_block + + +def prerequisites(lang_config, service, customs: dict[str, str]): + prereqs = [] + if lang_config["name"] != "C++": + prereqs.append( + para( + "For prerequisites, see the ", + link(title="README", href=f"{lang_config['readme']}#Prerequisites"), + f" in the `{lang_config['base_folder']}` folder.", + ) + ) + + if lang_config["name"] == "Python" and lang_config["sdk_ver"] == 3: + prereqs.append( + para( + "Install the packages required by these examples by running the following in a virtual environment:" + ) + ) + prereqs.append(code_block("python -m pip install -r requirements.txt")) + + elif lang_config["name"] == "C++" and lang_config["sdk_ver"] == 1: + prereqs.append( + para( + "Before using the code examples, first complete the installation and setup steps\n" + "for ", + link( + title="Getting Started", + href="https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/getting-started.html", + ), + "in the AWS SDK for\n" + "C++ Developer Guide.\n" + "This section covers how to get and build the SDK, and how to build your own code by using the SDK with a\n" + "sample Hello World-style application.\n", + ) + ) + prereqs.append( + para( + "Next, for information on code example structures and how to build and run the examples, see ", + link( + title="Getting started with the AWS SDK for C++ code examples", + href="https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/getting-started-code-examples.html", + ), + ". ", + ), + ) + + if service == "bedrock": + prereqs.append( + blockquote( + "⚠ You must request access to a model before you can use it. If you try to use the model (with the API or console) before you have requested access to it, you will receive an error message. For more information, see ", + link( + title="Model access", + href="https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html", + ), + ".", + ) + ) + + return h3( + "Prerequisites", + *prereqs, + commented_block("custom.prerequisites", customs["prerequisites"]), + ) diff --git a/.tools/readmes/includes/resources.jinja2 b/.tools/readmes/includes/resources.jinja2 deleted file mode 100644 index b5a6ca04338..00000000000 --- a/.tools/readmes/includes/resources.jinja2 +++ /dev/null @@ -1,9 +0,0 @@ -## Additional resources - -- [{{service['short']}} {{service['guide']['subtitle']}}]({{service['guide']['url']}}) -- [{{service['short']}} API Reference]({{service['api_ref']}}) -- [{{sdk['short']}} {{service['short']}} reference]({{lang_config['sdk_api_ref']}}) - - -{{ customs['resources'] -}} - diff --git a/.tools/readmes/includes/resources.py b/.tools/readmes/includes/resources.py new file mode 100644 index 00000000000..90d0c2771b5 --- /dev/null +++ b/.tools/readmes/includes/resources.py @@ -0,0 +1,22 @@ +def resources(sdk, service, lang_config, customs): + return block( + h2("Additional resources"), + unordered_list( + item( + link( + href=service["guide"]["url"], + title=f"{service['short']} {service['guide']['subtitle']}", + ) + ), + item( + link(href=service["api_ref"], title=f"{service['short']} API Reference") + ), + item( + link( + href=lang_config["sdk_api_ref"], + title=f"{sdk['short']} {service['short']} reference", + ) + ), + ), + commented_block("custom.resources", customs["resources"]), + ) diff --git a/.tools/readmes/includes/run_instructions.jinja2 b/.tools/readmes/includes/run_instructions.jinja2 deleted file mode 100644 index 463f3ab7716..00000000000 --- a/.tools/readmes/includes/run_instructions.jinja2 +++ /dev/null @@ -1,145 +0,0 @@ -### Instructions - -{% if lang_config['name'] == 'JavaScript' and lang_config['sdk_ver'] == 3 %} -**Note**: All code examples are written in ECMAscript 6 (ES6). For guidelines on converting to CommonJS, see -[JavaScript ES6/CommonJS syntax](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/sdk-examples-javascript-syntax.html). - -**Run a single action** - -```bash -node ./actions/ -``` - -**Run a scenario** -Most scenarios can be run with the following command: -```bash -node ./scenarios/ -``` -{% endif %} -{% if lang_config['name'] == '.NET' and lang_config['sdk_ver'] == 3 %} -For general instructions to run the examples, see the -[README](../README.md#building-and-running-the-code-examples) in the `dotnetv3` folder. - -Some projects might include a settings.json file. Before compiling the project, -you can change these values to match your own account and resources. Alternatively, -add a settings.local.json file with your local settings, which will be loaded automatically -when the application runs. - -After the example compiles, you can run it from the command line. To do so, navigate to -the folder that contains the .csproj file and run the following command: - -``` -dotnet run -``` - -Alternatively, you can run the example from within your IDE. - -{% endif %} -{% if lang_config['name'] == 'C++' %} -An executable is built for each source file in this folder. These executables are located in the build folder and have -"run_" prepended to the source file name, minus the suffix. See the "main" function in the source file for further instructions. - -For example, to run the action in the source file "my_action.cpp", execute the following command from within the build folder. The command -will display any required arguments. - -``` -./run_my_action -``` - -If the source file is in a different folder, instructions can be found in the README in that -folder. -{% endif %} -{% if lang_config['name'] == 'Swift' %} -To build any of these examples from a terminal window, navigate into its -directory, then use the following command: - -``` -$ swift build -``` - -To build one of these examples in Xcode, navigate to the example's directory -(such as the `ListUsers` directory, to build that example). Then type `xed.` -to open the example directory in Xcode. You can then use standard Xcode build -and run commands. -{% endif %} - - -{{ customs['instructions'] -}} - - -{% for hello_ex in hello %} -#### {{ hello_ex['title_abbrev'] }} - -This example shows you how to {{ hello_ex['synopsis'] }} - -{% if lang_config['name'] == 'Go' and lang_config['sdk_ver'] == 2 %} -``` -go run ./hello -``` -{% endif %} -{% if lang_config['name'] == 'Python' and lang_config['sdk_ver'] == 3 %} -``` -python {{ hello_ex['run_file'] }} -``` -{% endif %} -{% if lang_config['name'] == 'JavaScript' and lang_config['sdk_ver'] == 3 %} -```bash -node ./hello.js -``` -{% endif %} -{% if lang_config['name'] == 'Ruby' and lang_config['sdk_ver'] == 3 %} -``` -ruby {{ hello_ex['run_file'] }} -``` -{% endif %} -{% endfor %} - -{% if lang_config['name'] == 'Go' and lang_config['sdk_ver'] == 2 %} -#### Run a scenario - -All scenarios can be run with the `cmd` runner. To get a list of scenarios -and to get help for running a scenario, use the following command: - -``` -go run ./cmd -h -``` -{% endif %} - -{% for scenario in scenarios %} -#### {{scenario['title_abbrev']}} - -{% if scenario['synopsis'] %} -This example shows you how to {{scenario['synopsis']}} - -{% else %} -This example shows you how to do the following: - -{% endif %} -{% for syn in scenario['synopsis_list'] %} -- {{syn}} -{% endfor %} - - -{% if customs['scenario_prereqs'] %}{{ customs['scenario_prereqs'][scenario['id']] -}}{% endif %} - - -{% if lang_config['name'] == 'Python' and lang_config['sdk_ver'] == 3 and scenario["file"].endswith(".py") %} -Start the example by running the following at a command prompt: - -``` -python {{scenario['file']}} -``` - -{% elif lang_config['name'] == 'Ruby' and lang_config['sdk_ver'] == 3 %} -Start the example by running the following at a command prompt: - -``` -ruby {{scenario['file']}} -``` -{% endif %} - - -{% if customs['scenarios'] %}{{ customs['scenarios'][scenario['id']] -}}{% endif %} - - -{% endfor %} \ No newline at end of file diff --git a/.tools/readmes/includes/run_instructions.py b/.tools/readmes/includes/run_instructions.py new file mode 100644 index 00000000000..ac92f983508 --- /dev/null +++ b/.tools/readmes/includes/run_instructions.py @@ -0,0 +1,118 @@ + +def instructions(lang_config, customs: dict[str, str], hello: list): + instruction_blocks = [h2("Instructions")] + + if lang_config['name'] == 'JavaScript' and lang_config['sdk_ver'] == 3: + instruction_blocks.append(js_instructions()) + if lang_config['name'] == '.NET' and lang_config['sdk_ver'] == 3: + instruction_blocks.append(dotnet_3_instructions()) + if lang_config['name'] == 'C++': + instruction_blocks.append(cpp_instructions()) + if lang_config['name'] == 'swfit': + instruction_blocks.append(swift_instructions()) + + for hello_ex in hello: + instruction_blocks.append(hello_ex(hello)) + + + instruction_blocks.append(comment_block("custom.instructions", customs["instructions"])) + +def js_instructions(): + return block( + para( + strong("Note"), + ": All code examples are written in ECMAscript 6 (ES6). For guidelines on converting to CommonJS, see", + link(title="JavaScript ES6/CommonJS syntax", href="https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/sdk-examples-javascript-syntax.html"), "." + ), + block( + para(strong("Run a single action")), + code_block(lang="bash", "node ./actions/"), + ), + block( + para(strong("Run a scenario")), + code_block(lang="bash", "node ./scenarios/"), + ) + ) + +def dotnet_3_instructions(): + return block( + para( + "For general instructions to run the examples, see the ", + link(title="README", href="../README.md#building-and-running-the-code-examples") + " in the `dotnetv3` folder." + ), + para("Some projects might include a settings.json file. Before compiling the project, you can change these values to match your own account and resources. Alternatively, add a settings.local.json file with your local settings, which will be loaded automatically when the application runs."), + para("After the example compiles, you can run it from the command line. To do so, navigate to the folder that contains the .csproj file and run the following command:"), + code_block(language="sh", "dotnet_run"), + para("Alternatively, you can run the example from within your IDE.") + ) + + +def cpp_instructions(): + return block( + para("""An executable is built for each source file in this folder. These executables are located in the build folder and have "run_" prepended to the source file name, minus the suffix. See the "main" function in the source file for further instructions."""), + para("""For example, to run the action in the source file "my_action.cpp", execute the following command from within the build folder. The command will display any required arguments."""), + code_block(language="bash", "./run_my_action"), + para("""If the source file is in a different folder, instructions can be found in the README in that folder."""), + ) + + +def swift_instructions(): + return block( + para("To build any of these examples from a terminal window, navigate into its directory, then use the following command:"), + code_block(lanuage="bash", "$ swift build"), + para("To build one of these examples in Xcode, navigate to the example's directory (such as the `ListUsers` directory, to build that example). Then type `xed.` to open the example directory in Xcode. You can then use standard Xcode build and run commands."), + ) + + + +def hello_instructions(lang_config, example): + language_instructions = None + if lang_config['name'] == 'Go' and lang_config['sdk_ver'] == 2: + language_instructions = "go run ./hello" + if lang_config['name'] == 'Python' and lang_config['sdk_ver'] == 3: + language_instructions = f"python {example['run_file']}" + if lang_config['name'] == 'JavaScript' and lang_config['sdk_ver'] == 3: + language_instructions = f"node ./hello.js" + if lang_config['name'] == 'Ruby' and lang_config['sdk_ver'] == 3: + language_instructions = f"ruby {example['run_file']}" + + language_instructions = code_block(language_instructions) if language_instructions is not None + + return block( + h4(example['title_abbrev']), + para(f"This example shows you how to {example['synopsis']}"), + language_instructions + ) + + +def scenarios(lang_config, scenario_examples, customs): + scenario_blocks = [] + + if lang_config['name'] == 'Go' and lang_config['sdk_ver'] == 2: + scenario_blocks.append(block( + h4("Run a scenario"), + para("All scenarios can be run with the `cmd` runner. To get a list of scenarios and to get help for running a scenario, use the following command:"), + code_block("go run ./cmd -h") + )) + + for scenario in scenarios_examples: + scenario_blocks.append(h4(scenario['title_abbrev'])) + + if scenario['synopsis']: + scenario_blocks.append(para(f"This example shows you how to {scenario['synopsis']}")) + else: + scenario_blocks.append(para("This example shows you how to do the following:")) + + scenario_blocks.append(unordered_list([item(syn) for syn in scenario['synopsis_list']])) + scenario_custom = customs.get('scenario_prereqs', {}).get(scenario['id'], "") + scenario_blocks.append(f"cusom.scenario_prereqs.{scenario['id']}", scenario_custom) + + if lang_config['name'] == 'Python' and lang_config['sdk_ver'] == 3 and scenario["file"].endswith(".py"): + scenario_blocks.append(para("Start the example by running the following at a command prompt:")) + scenario_blocks.append(code_block(f"python {scenario['file']}")) + elif lang_config['name'] == 'Ruby' and lang_config['sdk_ver'] == 3: + scenario_blocks.append(para("Start the example by running the following at a command prompt:")) + scenario_blocks.append(code_block(f"ruby {scenario['file']}")) + customs_scenarios = customs.get('scenarios', {}).get(scenario['id'], "") + scenario_blocks.append(customs_scenarios) diff --git a/.tools/readmes/includes/tests.jinja2 b/.tools/readmes/includes/tests.jinja2 deleted file mode 100644 index fe1171a983f..00000000000 --- a/.tools/readmes/includes/tests.jinja2 +++ /dev/null @@ -1,25 +0,0 @@ -### Tests - -⚠ Running tests might result in charges to your AWS account. - -{% if lang_config['name'] != 'C++' %} - -To find instructions for running these tests, see the [README]({{lang_config['readme']}}#Tests) -in the `{{lang_config['base_folder']}}` folder. - -{% endif %} - -{% if lang_config['name'] == 'C++' and lang_config['sdk_ver'] == 1 %} - -```sh - cd - cmake -DBUILD_TESTS=ON - make - ctest -``` - -{% endif %} - - -{{ customs['tests'] -}} - diff --git a/.tools/readmes/includes/tests.py b/.tools/readmes/includes/tests.py new file mode 100644 index 00000000000..1b695ca2443 --- /dev/null +++ b/.tools/readmes/includes/tests.py @@ -0,0 +1,28 @@ +cpp_test = """ +cd +cmake -DBUILD_TESTS=ON +make +ctest +""" + + +def tests(lang_config): + test_blocks = [] + + if lang_config["name"] != "C++": + test_blocks.append( + para( + "To find instructions for running these tests, see the ", + link(title="README", href=f"{lang_config['readme']}#Tests"), + f"in the `{lang_config['base_folder']}` folder.", + ) + ) + + if lang_config["name"] == "C++" and lang_config["sdk_ver"] == 1: + test_blocks.append(code_block(lang="sh", code=cpp_test)) + + return block( + blockquote("⚠ Running tests might result in charges to your AWS account."), + *test_blocks, + comment_block("custom.tests", customs["tests"]), + )