From c9f155c25c5ba1cef43480a6f88a4188de49f363 Mon Sep 17 00:00:00 2001 From: David Souther Date: Wed, 30 Oct 2024 07:26:41 -0700 Subject: [PATCH 1/2] Update tools README.md to streamline things that are handled by update.py --- .tools/readmes/README.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/.tools/readmes/README.md b/.tools/readmes/README.md index 198a07bef89..dd426f962ac 100644 --- a/.tools/readmes/README.md +++ b/.tools/readmes/README.md @@ -20,10 +20,14 @@ and install packages by running the following commands in the `.tools/readmes` folder: ``` +cd .tools/readmes python -m venv .venv -.venv\Scripts\activate # Windows -source .venv/bin/activate # *nix -python -m pip install -r requirements.txt + +# Windows +.venv\Scripts\activate + +# Linux or MacOS +source .venv/bin/activate ``` Depending on how you have Python installed and on your operating system, @@ -37,7 +41,8 @@ authored for the SOS project. After you have authored metadata and snippet tags for your examples, run the following command in the root folder of the repo: ``` -python .tools/readmes/writeme.py --languages : --services +cd .tools/readmes # (if not already in the readme directory) +python -m writeme --languages : --services ``` WRITEME reads metadata and config data and generates READMEs in the service @@ -46,7 +51,7 @@ folder for the specified languages, versions, and services. For example, to generate an S3 README for Python: ``` -python .tools/readmes/writeme.py --languages Python:3 --services s3 +python -m writeme --languages Python:3 --services s3 ``` This creates a README.md file in the `python/example_code/s3` folder. @@ -65,7 +70,7 @@ This creates a README.md file in the `python/example_code/s3` folder. You can get inline usage info by using the `-h` flag: ``` -python .tools/readmes/writeme.py -h +python -m writeme -h ``` ### Configuration @@ -129,7 +134,7 @@ This creates the README.md files in `python/example_code/s3` and other folders. To build all READMEs for Rust: ``` -$ python .tools/readmes/writeme.py --languages Rust:1 +$ python -m writeme --languages Rust:1 INFO:root:Dry run, no changes will be made. DEBUG:root:Rendering Rust:1:acm DEBUG:root:Rendering Rust:1:api-gateway @@ -146,5 +151,5 @@ and complete folder override as the value. See dotnetv3 for an example. And yes, building all readmes for all languages after changing metadata or templates is now as easy as ``` -python .tools/readmes/writeme.py +python -m writeme ``` From 878de3c952b482749ccd63a3aedd6214d677c908 Mon Sep 17 00:00:00 2001 From: David Souther Date: Wed, 30 Oct 2024 10:00:43 -0700 Subject: [PATCH 2/2] Update README.md --- .tools/readmes/README.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/.tools/readmes/README.md b/.tools/readmes/README.md index dd426f962ac..879577e5728 100644 --- a/.tools/readmes/README.md +++ b/.tools/readmes/README.md @@ -9,15 +9,7 @@ This is an internal tool intended for use only by the AWS code examples team. ## Prerequisites -You must have a recent version of Python installed to run this tool, -and a recent version of pip (Python's package manager) to install the -required packages. - -### Install packages - -We recommend a virtual environment. Create a virtual environment -and install packages by running the following commands in the -`.tools/readmes` folder: +We recommend a virtual environment to run this tool. ``` cd .tools/readmes @@ -36,12 +28,14 @@ the commands might vary slightly. For example, on Windows, use `py` in place of ## Generate a README +> These instructions assume you're running the commands from the `.tools/writeme` +> 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 root folder of the repo: ``` -cd .tools/readmes # (if not already in the readme directory) python -m writeme --languages : --services ```