Merge pull request #2 from itk-dev/feature/documentation

Updated documentation

Author: rimi-itk

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+#### Link to ticket
+
+Please add a link to the ticket being addressed by this change.
+
+#### Description
+
+Please include a short description of the suggested change and the reasoning behind the approach you have chosen.
+
+#### Screenshot of the result
+
+If your change affects the user interface you should include a screenshot of the result with the pull request.
+
+#### Checklist
+
+- [ ] My code is covered by test cases.
+- [ ] My code passes our test (all our tests).
+- [ ] My code passes our static analysis suite.
+- [ ] My code passes our continuous integration process.
+
+If your code does not pass all the requirements on the checklist you have to add a comment explaining why this change 
+should be exempt from the list.
+
+#### Additional comments or questions
+
+If you have any further comments or questions for the reviewer please add them here.

CHANGELOG.md

@@ -7,4 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+* [PR-2](https://github.com/OS2web/os2web_key/pull/2)
+  Updated documentation
+* [PR-1](https://github.com/OS2web/os2web_key/pull/1)
+  Added OS2Web key module
+
 [Unreleased]: https://github.com/rimi-itk/os2web_key

README.md

@@ -2,20 +2,33 @@
 
 Key types and providers for OS2Web built on the [Key module](https://www.drupal.org/project/key).
 
+The OS2Web key module provides two _key types_, [Certificate](#certificate) and [OpenID Connect
+(OIDC)](#openid-connect-oidc). Two _key providers_, [Azure Key Vault](#azure-key-vault) and [Infisical](#infisical), are
+planned, but not yet implemented.
+
+See [the Key Developer Guide](https://www.drupal.org/docs/contributed-modules/key/developer-guide) for details in how to
+use keys in Drupal.
+
 ## Installation
 
 ``` shell
 composer require os2web/os2web_key
 drush pm:install os2web_key
 ```
 
+Keys are managed on `/admin/config/system/keys`.
+
 ## Key types
 
 ### Certificate
 
 This key type handles [PKCS 12](https://en.wikipedia.org/wiki/PKCS_12) or [Privacy-Enhanced Mail
 (PEM)](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) certificate with an optional password (passphrase).
 
+Managing the key:
+
+!["Certificate" key type form](docs/assets/key-type-certificate.png)
+
 Use in a form:
 
 ``` php
@@ -56,6 +69,10 @@ $key = $repository->getKey('my_key');
 
 ### OpenID Connect (OIDC)
 
+Managing the key:
+
+!["OpenID Connect (OIDC)" key type form](docs/assets/key-type-oidc.png)
+
 Example use in a form:
 
 ``` php
@@ -87,18 +104,15 @@ $key = $repository->getKey('openid_connect_ad');
 ] = $helper->getOidcValues($key);
 ```
 
-See [the Key Developer Guide](https://www.drupal.org/docs/contributed-modules/key/developer-guide) for details and more
-examples.
-
 ## Providers
 
-### `@todo` Azure Key Vault
+### Azure Key Vault
 
-<https://azure.microsoft.com/en-us/products/key-vault>
+`@todo` <https://azure.microsoft.com/en-us/products/key-vault>
 
-### `@todo` Infisical
+### Infisical
 
-<https://infisical.com/>
+`@todo` <https://infisical.com/>
 
 ## Coding standards