Updates to documentation.

Author: rlhagerm

Diff for: .github/workflows/writeme.yml

@@ -29,7 +29,7 @@ jobs:
           python-version: 3.11  # install the python needed
       - name: Install dependencies
         run: >-
-          python3 -m pip install -r .tools/readmes/requirements.txt
+          python3 -m pip install -r .tools/scanners/requirements.txt
       - name: Check WRITEMEs
         run: >-
           python3 .tools/scanners/writeme.py --check --diff

Diff for: .tools/scanners/README.md

@@ -2,17 +2,19 @@
 
 ## Overview
 
-Describes WRITEME, a tool to automatically generate service-level READMEs from
-metadata and Jinja templates.
+Describes a set of scanners to generate documents from the example metadata in this repository.
 
-This is an internal tool intended for use only by the AWS code examples team.
+- [writeme.py](#WRITEME) - generates READMEs from metadata. Enabled for all SDK languages.
+- [catalog.py](#Catalog) - generates catalog files with example listings. Currently enabled for Python only.
+
+### General Information
 
 ## Prerequisites
 
-We recommend a virtual environment to run this tool.
+We recommend a virtual environment to run these tools.
 
 ```
-cd .tools/readmes
+cd .tools/scanners
 python -m venv .venv
 
 # Windows
@@ -26,30 +28,6 @@ Depending on how you have Python installed and on your operating system,
 the commands might vary slightly. For example, on Windows, use `py` in place of
 `python` and uses backslashes in the `venv` path.
 
-## Generate a README
-
-> These instructions assume you're running the commands from the `.tools/readmes`
-> directory, using the venv installed there.
-
-WRITEME creates content primarily from metadata you have already
-authored for the SOS project. After you have authored metadata and snippet tags
-for your examples, run the following command in the `.tools/readmes` folder:
-
-```
-python -m writeme --languages <language>:<version> --services <service>
-```
-
-WRITEME reads metadata and config data and generates READMEs in the service
-folder for the specified languages, versions, and services.
-
-For example, to generate an S3 README for Python:
-
-```
-python -m writeme --languages Python:3 --services s3
-```
-
-This creates a README.md file in the `python/example_code/s3` folder.
-
 ### Parameters
 
 - `--languages` must match a top-level language:version in sdks.yaml.
@@ -58,8 +36,8 @@ This creates a README.md file in the `python/example_code/s3` folder.
   `saved_readme` value in config.py (such as README.old.md).
 - `--verbose` When set, output verbose debugging info.
 - `--dry-run`, `--no-dry-run` In dry run, compare current vs generated and exit with failure if they do not match.
-- `--check` Verifies whether the existing README.md matches the proposed new README.md
-  (but does not write a new README.md). This is the same check that is run by the GitHub action.
+- `--check` Verifies whether the existing generated file matches the generated content.
+  (but does not write a new file). This is the same check that is run by the GitHub action.
 
 You can get inline usage info by using the `-h` flag:
 
@@ -73,6 +51,7 @@ Additional configuration is kept in `config.py`.
 
 - `entities` is a dictionary of entities that are not otherwise defined in
   services.yaml.
+- `catalog_filename` is the base name for generated catalog files.
 - `language` is a dictionary of language and version for each SDK. Fields are:
   - `base_folder` the root folder for the SDK version.
   - `service_folder` a Jinja template of the service folder for the SDK version.
@@ -83,6 +62,38 @@ Additional configuration is kept in `config.py`.
     and if the generated link is wrong, you can update it manually. On subsequent runs
     of WRITEME, the existing link is kept.
 
+
+### WRITEME
+WRITEME is a tool to automatically generate service-level READMEs from
+metadata and Jinja templates.
+
+This is an internal tool intended for use only by the AWS code examples team.
+
+## Generate a README
+
+> These instructions assume you're running the commands from the `.tools/scanners`
+> directory, using the venv installed there.
+
+WRITEME creates content primarily from metadata you have already
+authored for the SOS project. After you have authored metadata and snippet tags
+for your examples, run the following command in the `.tools/scanners` folder:
+
+```
+python -m writeme --languages <language>:<version> --services <service>
+```
+
+WRITEME reads metadata and config data and generates READMEs in the service
+folder for the specified languages, versions, and services.
+
+For example, to generate an S3 README for Python:
+
+```
+python -m writeme --languages Python:3 --services s3
+```
+
+This creates a README.md file in the `python/example_code/s3` folder.
+
+
 ### Custom content
 
 Custom content can be per-SDK or per-README.
@@ -114,13 +125,13 @@ empty if you don't need custom content.
 versions, and services.
 
 ```
-python .tools/readmes/writeme.py --languages <language1>:<version> <language2>:<version> --service <service1> <service2>
+python .tools/scanners/writeme.py --languages <language1>:<version> <language2>:<version> --service <service1> <service2>
 ```
 
 For example, to generate S3 and STS READMEs for Python sdk version 3 and Go sdk version 2:
 
 ```
-python .tools/readmes/writeme.py --languages Python:3 Go:2 --services s3 sts
+python .tools/scanners/writeme.py --languages Python:3 Go:2 --services s3 sts
 ```
 
 This creates the README.md files in `python/example_code/s3` and other folders.
@@ -147,3 +158,32 @@ And yes, building all readmes for all languages after changing metadata or templ
 ```
 python -m writeme
 ```
+
+### Catalog
+Catalog.py is a tool to automatically generate service-level example catalogs (examples_catalog.json) from metadata using shared document generation tools.
+
+This is an internal tool intended for use only by the AWS code examples team.
+
+## Generate a Catalog
+
+> These instructions assume you're running the commands from the `.tools/scanners`
+> directory, using the venv installed there.
+
+WRITEME creates content primarily from metadata you have already
+authored for the SOS project. After you have authored metadata and snippet tags
+for your examples, run the following command in the `.tools/scanners` folder:
+
+```
+python -m catalog --languages <language>:<version> --services <service>
+```
+
+Catalog.py reads metadata and config data and generates listings of examples in the service
+folder for the specified languages and versions. The file will not be generated if no examples exist.
+
+For example, to generate an S3 README for Python:
+
+```
+python -m catalog --languages Python:3 --services s3
+```
+
+This creates an `examples_catalog.json` file in the `python/example_code/s3` folder.

Diff for: rustv1/README.md

@@ -98,7 +98,7 @@ these examples in an isolated environment.
 
 ## Updating Rust Version
 
-If a rust version releases (most likely) a clippy or has some other breaking change, the Weathertop dashboard will go red. The easiest way to handle this is to run `./tools/set_rust_version.py [rust_version]` (using a venv with the appropriate requirements), creating a commit with those updates, and then running `cargo clippy --fix` in the appropriate folder before making a second commit with those fixes. Line numbers will certainly change, so don't forget to run WRITEME - `./.tools/readmes/.venv/bin/python ./.tools/readmes/writeme.py --languages Rust:1`.
+If a rust version releases (most likely) a clippy or has some other breaking change, the Weathertop dashboard will go red. The easiest way to handle this is to run `./tools/set_rust_version.py [rust_version]` (using a venv with the appropriate requirements), creating a commit with those updates, and then running `cargo clippy --fix` in the appropriate folder before making a second commit with those fixes. Line numbers will certainly change, so don't forget to run WRITEME - `./.tools/scanners/.venv/bin/python ./.tools/readmes/writeme.py --languages Rust:1`.
 
 ## Contributing