Update documentation in preparation for publication

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Michael Rans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

PULL_REQUEST_TEMPLATE.md

@@ -4,6 +4,7 @@ Version for this PR: 202*.*.*
 
 - [] [GitHub issue or issues if relevant](https://www.google.com)
 
+
 ## Major file changes
 Describe major file changes in brief
 
@@ -14,3 +15,4 @@ Outline why other files have changed
 
 `hdx-cli-toolkit` uses the CalVer versioning scheme with format YYYY.MM.Micro i.e. 2022.12.1 which is updated manually in `pyproject.toml`. The "Micro" component is simply an integer increased by 1 at each version, starting from 0.
 - [] Version updated in `pyproject.toml` and PR description
+- [] Update README.md and DEMO.md with any new CLI commands

README.md

@@ -2,27 +2,32 @@
 
 ## Overview
 
-This toolkit is intended to provide a commandline interface to HDX to allow for bulk modification operations and other administrative activities, in the first instance to carry out a bulk quarantine action on all the datasets in an organization. It is inspired by [hdx-update-cods-level](https://github.com/b-j-mills/hdx-update-cods-level/tree/main).
+This toolkit provides a commandline interface to the [Humanitarian Data Exchange](https://data.humdata.org/) (HDX) to allow for bulk modification operations and other administrative activities such as getting `id` values for users and organization. It is useful for those managing HDX and developers building data pipelines for HDX. The currently supported commands are as follows:
 
-## Installation
-`hdx-cli-toolkit` is a Python application. 
+```
+  configuration              Print configuration information to terminal
+  get_organization_metadata  Get an organization id and other metadata
+  get_user_metadata          Get user id and other metadata
+  list                       List datasets in HDX
+  print                      Print datasets in HDX to the terminal
+  quickcharts                Upload QuickChart JSON description to HDX
+  showcase                   Upload showcase to HDX
+  update                     Update datasets in HDX
+  update_resource            Update a resource in HDX
+```
 
-For developers the code should be cloned installed from the [GitHub repo](https://github.com/OCHA-DAP/hdx-cli-toolkit), and a virtual enviroment created:
+It is a thin wrapper to the [hdx-python-api](https://github.com/OCHA-DAP/hdx-python-api) written by Mike Rans.
 
-```shell
-python -m venv venv
-source venv/Scripts/activate
-```
+The library requires some configuration, described below, to authenticate to the HDX instance.
 
-And then an editable installation created:
+## Installation
+`hdx-cli-toolkit` is a Python application published to the PyPI package repository, therefore it can be installed easily with:
 
-```shell
-pip install -e .
-```
+```pip install hdx-cli-toolkit```
 
-For users the best route is probably to use [pipx](https://pypi.org/project/pipx/) to install which will provide `hdx-toolkit` globally in its own environment.
+Users may prefer to make a global, isolated installation using [pipx](https://pypi.org/project/pipx/) which will make the `hdx-toolkit` commands available across their projects:
 
-In either case there is a small amount of configuration required.
+```pipx install hdx-cli-toolkit```
 
 `hdx-cli-toolkit` uses the `hdx-python-api` library, this requires the following to be added to a file called `.hdx_configuration.yaml` in the user's home directory.
 
@@ -38,7 +43,6 @@ hdx-cli-toolkit:
     user_agent: hdx_cli_toolkit_ih
 ```
 
-
 ## Usage
 
 The `hdx-toolkit` is built using the Python `click` library. Details of the currently implemented commands can be revealed by running `hdx-toolkit --help`:
@@ -74,6 +78,21 @@ A detailed walk through of commands can be found in the [DEMO.md](DEMO.md) file
 
 ## Contributions
 
+For developers the code should be cloned installed from the [GitHub repo](https://github.com/OCHA-DAP/hdx-cli-toolkit), and a virtual enviroment created:
+
+```shell
+python -m venv venv
+source venv/Scripts/activate
+```
+
+And then an editable installation created:
+
+```shell
+pip install -e .
+```
+
+The library is then configured, as described above.
+
 This project users a GitHub Action to run tests and linting. It requires the following environment variables/secrets to be set in the `test` environment:
 
 ```
@@ -84,9 +103,7 @@ USER_AGENT - environment variable. Value: hdx_cli_toolkit_gha
 PREPREFIX - - environment variable. Value: [YOUR_organization]
 ```
 
-Testing uses a mock for the HDX so a live HDX_KEY is not required.
+Most tests use mocking in place of HDX, although the `test_integration.py` suite runs against the `stage` server.
 
 New features should be developed against a GitHub issue on a separate branch with a name starting GH[issue number]_ . `PULL_REQUEST_TEMPLATE.md` should be used in preparing pull requests. Versioning is updated manually in `pyproject.toml` and is described in the template, in brief it is CalVer `YYYY.MM.Micro`.
 
-
-