From 6ca79c92be6c08c462b0c49770bbd1b1460c546a Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 31 Jul 2023 08:55:33 +0100 Subject: [PATCH] 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 --- README.md | 64 ++++++++++++++++++++++++++++++++++++++++++-------- docs/README.md | 7 ------ 2 files changed, 54 insertions(+), 17 deletions(-) delete mode 100644 docs/README.md diff --git a/README.md b/README.md index d9d365ba..851ff147 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,25 @@ -# 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. + -## Using the template + +[website]: https://github-pages.arc.ucl.ac.uk/python-tooling +[UCL ARC]: https://ucl.ac.uk/arc +[cookieninja]: https://libraries.io/pypi/cookieninja + -1. Install [cookieninja](https://libraries.io/pypi/cookieninja) +## Using this template + +1. Install [cookieninja] ``` pip install cookieninja ``` @@ -20,7 +27,7 @@ If you're making a package within a community that has an existing package templ ``` 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 ``` + +- 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. diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index bc019544..00000000 --- a/docs/README.md +++ /dev/null @@ -1,7 +0,0 @@ -### Building 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.