README fixes. (#119)

Update the main root README to be more sane following the repo merge.
Remove the docs/README and integrate to the main.

Comments on clarity, language etc very welcome.

Follows on from:
* #70

---------

Co-authored-by: Patrick Roddy <[email protected]>

README.md

@@ -1,26 +1,33 @@
-# ARC Python Package Template
+# UCL ARC Python Recommendations
 
-⚠️ This repository is still under construction! ⚠️
+This is repository collects the [UCL ARC] recommendations for a Research Software project in Python.
+It contains a template for new Python packages and a [website] documenting our recommendations.
+We've turned on [discussions](https://github.com/UCL-ARC/python-tooling/discussions) for this repo, and we welcome questions there or in the `#programming-help` channel on the [UCL research software hub slack](https://www.ucl.ac.uk/advanced-research-computing/community/ucl-research-programming-hub).
 
-[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+🍪🥷 Our template is a [cookieninja] template which automatically creates new Python packages with our recommended tooling set up and ready to go.
 
-This is a Python package template for new ARC Python packages.
-It automatically creates new Python packages with the recommended tooling set up and ready to go.
-The recommended tooling is documented on the [UCL-ARC/python-tooling website](http://github-pages.arc.ucl.ac.uk/python-tooling/).
+> **Note**
+> If you're making a package within a community that has an existing package template (e.g., [`scikit-hep`](https://github.com/scikit-hep/cookie)), we recommend using their template instead of this one.
 
-If you're making a package within a community that has an existing package template (e.g., [`scikit-hep`](https://github.com/scikit-hep/cookie)), we recommend using their template instead of this one.
+<!-- links here -->
 
-## Using the template
+<!-- prettier-ignore-start -->
+[website]: https://github-pages.arc.ucl.ac.uk/python-tooling
+[UCL ARC]: https://ucl.ac.uk/arc
+[cookieninja]: https://libraries.io/pypi/cookieninja
+<!-- prettier-ignore-end -->
 
-1. Install [cookieninja](https://libraries.io/pypi/cookieninja)
+## Using this template
+
+1. Install [cookieninja]
    ```
    pip install cookieninja
    ```
 2. Run cookieninja in the desired directory
    ```
    cookieninja gh:ucl-arc/python-tooling
    ```
-   If you have this repo locally (this may be the case if you are developing), you can alternatively run the following:
+   If you have this repo locally (this may be the case if you are developing), you can run the following:
    ```
    cookieninja /path/to/your/checkout/of/python-tooling
    ```
@@ -86,7 +93,44 @@ If you're making a package within a community that has an existing package templ
 
 ## Notes for developers
 
+### Contributing
+
+The [website] and source pages are open to contributions but must be reviewed by a member or associate member of ARC.
+We might be slow to approve new tool suggestions (since we'll probably want to discuss them first), but bug reports (and fixes) are very welcome from anyone!
+
+Pages all live in the [docs/pages](https://github.com/UCL-ARC/python-tooling/tree/main/docs/pages) sub-directory, and are written in markdown.
+
+To contribute:
+
+1. Create a new branch (or fork if you're not in ARC-collaborations).
+2. Modify an existing page, create a new one, or tweak the template.
+   a. Run [pre-commit](https://pre-commit.com) which will lint your changes.
+   b. Check the tests pass if you modified the template (`pytest -s`).
+3. Open a pull request with changes.
+4. Someone who did not contribute to the PR should review it.
+5. If approved, the reviewer should merge the PR.
+6. If changes requested, the PR author should address the comments, then ask for review again.
+
+### Development
+
 - To run cookieninja using a specific branch of the template:
+
   ```
   cookieninja https://github.com/UCL-ARC/python-tooling --checkout <branch-name>
   ```
+
+- To run the tests locally:
+
+  ```
+  pytest -s
+  ```
+
+  We do a test cookiecut of a dummy package and install it to ensure the template setup works.
+
+- To build the docs locally
+
+  1.  [Install jekyll](https://jekyllrb.com/docs/installation)
+  2.  Run `bundle install` from the root of this repository to install dependencies
+  3.  Run `bundle exec jekyll serve` from the root directory of this repository. This should fire up a local web server and tell you its address. By default the server will automatically refresh the HTML pages if any changes are made to the markdown sources.
+
+  See the [jekyll docs](https://jekyllrb.com/docs) for more info.