Add documentation (#18)

cariad · Jan 23, 2021 · 9bf8d0e · 9bf8d0e
1 parent 3809aeb
commit 9bf8d0e
Show file tree

Hide file tree

Showing 10 changed files with 111 additions and 131 deletions.
diff --git 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
@@ -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
@@ -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 → docs/examples/aws-mfa-on-command-line.md b/docs/examples/awsmfa.md → 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
@@ -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
@@ -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).
+
 <!-- - `wev` can [request a CodeArtifact authorisation token on behalf of pipenv](/examples/awscodeartifact.md). -->
 
 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
@@ -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
diff --git 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
@@ -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