From 9bf8d0e44b74f477f73c5dcc6368c14287aab2d0 Mon Sep 17 00:00:00 2001 From: Cariad Eccleston Date: Sat, 23 Jan 2021 12:14:57 +0000 Subject: [PATCH] Add documentation (#18) --- docs/README.md | 7 +- docs/configuration/index.md | 5 ++ docs/configuration/schema.md | 12 +-- .../{awsmfa.md => aws-mfa-on-command-line.md} | 6 +- docs/examples/aws-profile-per-project.md | 69 ++++++++++++++++ docs/index.md | 8 +- docs/plugins/index.md | 14 ++-- docs/plugins/wev-awsmfa.md | 34 -------- docs/plugins/wev-echo.md | 82 +------------------ mkdocs.yml | 5 +- 10 files changed, 111 insertions(+), 131 deletions(-) create mode 100644 docs/configuration/index.md rename docs/examples/{awsmfa.md => aws-mfa-on-command-line.md} (76%) create mode 100644 docs/examples/aws-profile-per-project.md delete mode 100644 docs/plugins/wev-awsmfa.md diff --git a/docs/README.md b/docs/README.md index db4b569..65a518c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,12 @@ [![codecov](https://codecov.io/gh/cariad/wev/branch/main/graph/badge.svg?token=MJ4M989DEX)](https://codecov.io/gh/cariad/wev) -`wev` is a command line tool for resolving environment variables then running shell commands. +`wev` is a cross-platform command line tool for resolving temporary environment variables. + +For example: + +- `wev` can [create a multi-factor authenticated Amazon Web Services session](https://wevcli.app/examples/aws-mfa-on-command-line). +- `wev` can [set Amazon Web Services named profiles per-project](https://wevcli.app/examples/aws-profile-per-project). **User and developer documentation is online at [wevcli.app](https://wevcli.app).** diff --git a/docs/configuration/index.md b/docs/configuration/index.md new file mode 100644 index 0000000..ff081cf --- /dev/null +++ b/docs/configuration/index.md @@ -0,0 +1,5 @@ +# Overview + +- โš™๏ธ `wev` is configurable. [Configuration files](schema) are YAML dictionaries. +- ๐ŸŒ `wev` is contextual. [Directories](directories) are significant. +- ๐Ÿ‘ฉโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ง `wev` is collaborative. Team and personal configuration [filenames](filenames) are significant. diff --git a/docs/configuration/schema.md b/docs/configuration/schema.md index f8fd7d3..309a6a4 100644 --- a/docs/configuration/schema.md +++ b/docs/configuration/schema.md @@ -1,16 +1,16 @@ # Schema -`wev` configurations are dictionaries descibed as YAML. +`wev` configuration files are YAML dictionaries. ## Keys -Each _key_ is the name(s) of the environment variable(s) to set. +Each key is the name (or names) of the environment variable (or variables) to set. -It must be either a _string_ or a _list_, depending on whether the plugin resolves _one_ or _more than one_ value. +It must be either a string or a list, depending on whether the plugin resolves one or more than one value. ## Values -Each _value_ is a `plugin` property which describes the `id` of the plugin in invoke and any plugin-specific configuration. +Each value is a `plugin` property which describes the `id` of the plugin in invoke and any plugin-specific configuration. ## Examples @@ -46,7 +46,7 @@ MY_ADDRESS: ### Multiple environment variables by one plugin -The [wev-awsmfa](/plugins/wev-awsmfa) plugin creates temporary Amazon Web Services sessions, which are described by three values: a key identifier, a secret and a session token. +The [wev-awsmfa](https://github.com/cariad/wev-awsmfa) plugin creates temporary Amazon Web Services sessions, which are described by three values: a key identifier, a secret and a session token. To configure plugins that resolve multiple values, the _key_ must be a _list_. @@ -59,4 +59,4 @@ This example configures `wev` to resolve `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS duration: 30 ``` -Each plugin's own documentation will describe whether the _key_ must be a _string_ or a _list_. +Each plugin's own documentation will describe whether the key must be a string or a list. diff --git a/docs/examples/awsmfa.md b/docs/examples/aws-mfa-on-command-line.md similarity index 76% rename from docs/examples/awsmfa.md rename to docs/examples/aws-mfa-on-command-line.md index 37f41c1..e5376b8 100644 --- a/docs/examples/awsmfa.md +++ b/docs/examples/aws-mfa-on-command-line.md @@ -1,10 +1,12 @@ # Amazon Web Services multi-factor authentication on the command line -Say you're a software developer working for a client who gave you an IAM user that requires multi-factor authentication. +You're a software developer working for a client who gave you an IAM user that requires multi-factor authentication. All of your work for this client is in subdirectories of `~/client-foo`. -You'd like to run the `aws` CLI, but you can't pass one-time tokens to it to authenticate. `wev` can help. +You'd like to run the `aws` CLI, but you can't pass one-time tokens to it to authenticate. + +`wev`'s contextual environment variables can manage that for you. 1. Install `wev` and `wev-awsmfa`: diff --git a/docs/examples/aws-profile-per-project.md b/docs/examples/aws-profile-per-project.md new file mode 100644 index 0000000..97f959a --- /dev/null +++ b/docs/examples/aws-profile-per-project.md @@ -0,0 +1,69 @@ +# Amazon Web Services named profile per project + +You're a freelance software developer. You have two directories to distinguish between your personal and client projects: + +- `~/code` for personal projects. +- `~/client-foo` for client _foo_'s projects. + +You use Amazon Web Services for both personal and client projects, and you have AWS named profiles set up for each account you interact with: + +- The `personal` profile for your personal AWS account. +- The `foo` profile for client _foo_'s AWS account. + +Right now, you need to remember to run `aws` with `--profile personal` or `--profile foo` depending on the project you're working on. + +However, `wev`'s contextual environment variables can manage that for you. + +1. Install `wev`: + + ```bash + pip3 install wev + ``` + +2. Create `~/code/wev.yml`: + + ```yaml + AWS_DEFAULT_PROFILE: + plugin: + id: wev-echo + value: personal + ``` + +3. Create `~/client-foo/wev.yml`: + + ```yaml + AWS_DEFAULT_PROFILE: + plugin: + id: wev-echo + value: foo + ``` + +4. Open a terminal and `cd` into `~/code`. Verify that the _personal_ named profile is used: + + ```bash + cd ~/code + wev aws sts get-caller-identity + ``` + + ```json + { + "UserId": "000000000000", + "Account": "000000000000", + "Arn": "arn:aws:iam::000000000000:user/you" + } + ``` + +4. Open a terminal and `cd` into `~/client-foo`. Verify that the _foo_ named profile is used: + + ```bash + cd ~/client-foo + wev aws sts get-caller-identity + ``` + + ```json + { + "UserId": "111111111111", + "Account": "111111111111", + "Arn": "arn:aws:iam::111111111111:user/contractor" + } + ``` diff --git a/docs/index.md b/docs/index.md index d67733e..9aa572e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,13 +4,15 @@ For example: -- `wev` can [create a multi-factor authenticated Amazon Web Services session](/examples/awsmfa). +- `wev` can [create a multi-factor authenticated Amazon Web Services session](/examples/aws-mfa-on-command-line). +- `wev` can [set Amazon Web Services named profiles per-project](/examples/aws-profile-per-project). + In a nutshell: - โš™๏ธ Extensible via **[plugins](/plugins)**. - ๐Ÿ‘ทโ€โ™€๏ธ **[Create your own plugins](/create-a-plugin)** to suit any need. -- ๐Ÿ”Ž **[Contextual](/configuration/directories)**. Resolve different environment variables in different working directories. -- ๐Ÿ”Ž **[Team and private](/configuration/filenames)** configurations live side-by-side. +- ๐ŸŒ **[Contextual](/configuration/directories)**. Resolve different environment variables in different working directories. +- ๐Ÿ‘ฉโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ง **[Team and private](/configuration/filenames)** configurations live side-by-side. - ๐Ÿ“‹ **Caches** values to avoid delays and prompts. diff --git a/docs/plugins/index.md b/docs/plugins/index.md index e26d335..40d7a93 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -1,9 +1,13 @@ -# Introduction +# Available plugins -This isn't a comprehensive list of plugins for `wev`. Anyone can [create a plugin](/create-a-plugin). +This isn't a comprehensive list of plugins for `wev`, since anyone can [create a plugin](/create-a-plugin) and publish it independently. -## Adding your plugin to this list +Notable plugins include: -If you've built and published a plugin for `wev` then--first of all--_awesome!_ +| Name | Description | +|----------------------------------------------------------------------|-------------------------------------------------| +| [wev-awscodeartifact](https://github.com/cariad/wev-awscodeartifact) | Amazon Web Services CodeArtifact authorisation | +| [wev-awsmfa](https://github.com/cariad/wev-awsmfa) | Amazon Web Services multi-factor authentication | +| [wev-echo](wev-echo) | Echos strings | -Please [raise an issue](https://github.com/cariad/wev/issues/new) summarising your plugin and where I can find it, and we'll collaborate on the documentation and promotion. +To submit your own plugin for inclusion in this list, send me a pull request for review and I'll take a look. And thanks! diff --git a/docs/plugins/wev-awsmfa.md b/docs/plugins/wev-awsmfa.md deleted file mode 100644 index e4015f3..0000000 --- a/docs/plugins/wev-awsmfa.md +++ /dev/null @@ -1,34 +0,0 @@ -# wev-awsmfa - -## Overview - -`wev-awsmfa` adds support for Amazon Web Services multi-factor authentication. - -The source code is on GitHub at [cariad/wev-awsmfa](https://github.com/cariad/wev-awsmfa). - -## Installation - -```python -pip3 install wev-awsmfa -``` - -## Configuration - -### Keys - -`wev-awsmfa` must be configured to resolve _three_ environment variables: - -1. The AWS access key ID. You likely want this to be `AWS_ACCESS_KEY_ID`. -1. The AWS secret key. You likely want this to be `AWS_SECRET_ACCESS_KEY`. -1. The AWS session token. You likely want this to be `AWS_SESSION_TOKEN`. - -### Properties - -| Property | Required | Description | Default | -|------------|----------|-----------------------------------------------|-------------------------------------------| -| duration | โจฏ | Duration of the temporary session in seconds. | 900 | -| mfa_device | โจฏ | ARN of the multi-factor device to use. | _Will attempt to discover automatically._ | - -## Examples - -- [Amazon Web Services multi-factor authentication on the command line](/examples/awsmfa) diff --git a/docs/plugins/wev-echo.md b/docs/plugins/wev-echo.md index 49fc9c8..b37cb9b 100644 --- a/docs/plugins/wev-echo.md +++ b/docs/plugins/wev-echo.md @@ -1,90 +1,16 @@ # wev-echo -## Overview - `wev-echo` resolves to hard-coded values. -## Installation - -`wev-echo` is bundled with `wev`. +`wev-echo` is bundled with `wev` and so is always available without needing to be explicitly installed. ## Configuration | Property | Required | Description | |-----------|----------|---------------------------------------------------------------------------------| -| separator | โจฏ | Separator to insert between values when `value` is a list. Defaults to a space. | -| value | โœ”๏ธ | Value to resolve to. String or list of strings. | +| separator | | Separator to insert between values when `value` is a list. Defaults to a space. | +| value | โœ” | Value to resolve to. String or list of strings. | ## Examples -### Amazon Web Services profile - -Say you're a freelance software developer. - -You have two directories on your develpment machine: - -- `~/code` for personal projects. -- `~/client-foo` for client _foo_'s projects. - -Both of these projects use Amazon Web Services, and you use the `aws` application daily whether you're working on personal or client projects. - -You have AWS named profiles set up for each of these areas: - -- The `personal` profile holds credentials for your personal Amazon Web Services account. -- The `foo` profile holds credentials for client _foo_'s Amazon Web Services account. - -Right now, you need to remember to run `aws` with `--profile personal` or `--profile foo` depending on the project you're working on. `wev` can help. - -1. Install `wev`: - - ```bash - pip3 install wev - ``` - -2. Create `~/code/wev.yml`: - - ```yaml - AWS_DEFAULT_PROFILE: - plugin: - id: wev-echo - value: personal - ``` - -3. Create `~/client-foo/wev.yml`: - - ```yaml - AWS_DEFAULT_PROFILE: - plugin: - id: wev-echo - value: foo - ``` - -4. Open a terminal and `cd` into `~/code`. Verify that the _personal_ named profile is used: - - ```bash - cd ~/code - wev aws sts get-caller-identity - ``` - - ```json - { - "UserId": "000000000000", - "Account": "000000000000", - "Arn": "arn:aws:iam::000000000000:user/personal-you" - } - ``` - -4. Open a terminal and `cd` into `~/client-foo`. Verify that the _foo_ named profile is used: - - ```bash - cd ~/client-foo - wev aws sts get-caller-identity - ``` - - ```json - { - "UserId": "111111111111", - "Account": "111111111111", - "Arn": "arn:aws:iam::111111111111:user/professional-you" - } - ``` +- [Amazon Web Services named profile per project](/examples/aws-profile-per-project) diff --git a/mkdocs.yml b/mkdocs.yml index 2e417df..5914754 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,15 +41,16 @@ nav: - CONTRIBUTING.md - Licence: LICENSE.md - Configuration: + - configuration/index.md - configuration/schema.md - configuration/directories.md - configuration/filenames.md - Examples: - - examples/awsmfa.md + - examples/aws-mfa-on-command-line.md + - examples/aws-profile-per-project.md - Plugins: - plugins/index.md - plugins/wev-echo.md - - plugins/wev-awsmfa.md - Create a plugin: - Introduction: create-a-plugin/index.md - Preparation: create-a-plugin/preparation.md