Skip to content

Update tools README.md to streamline things that are handled by update.py #7023

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 30, 2024
Merged

Update tools README.md to streamline things that are handled by update.py #7023

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c9f155c
Update tools README.md to streamline things that are handled by updat…
DavidSouther Oct 30, 2024
878de3c
Update README.md
DavidSouther Oct 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 16 additions & 17 deletions .tools/readmes/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,21 +9,17 @@ 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
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,
Expand All @@ -32,12 +28,15 @@ 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:

```
python .tools/readmes/writeme.py --languages <language>:<version> --services <service>
python -m writeme --languages <language>:<version> --services <service>
```

WRITEME reads metadata and config data and generates READMEs in the service
Expand All @@ -46,7 +45,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.
Expand All @@ -65,7 +64,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
Expand Down Expand Up @@ -129,7 +128,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
Expand All @@ -146,5 +145,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
```
Loading