From ad567bf51bddf4fa4f4d6046299aaf3fd5e449ad Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Thu, 18 Sep 2025 14:11:30 +0100 Subject: [PATCH 1/5] First pass. --- README.md | 43 ++++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 36521a78..b0f86d20 100644 --- a/README.md +++ b/README.md @@ -5,44 +5,45 @@ -This 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 `#helpme` channel on the -[UCL research programming hub Slack](https://www.ucl.ac.uk/advanced-research-computing/community/ucl-research-programming-hub). +This 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. -🍪 Our template is a [cookiecutter] template which automatically creates new -Python packages with our recommended tooling set up and ready to go. +🍪 Our template uses [cookiecutter] to can create new Python packages with our preferred tools set up and ready to go. > [!NOTE] -> If you're making a package within a community that has an existing -> package template (e.g., [`SciKit-Surgery`](https://github.com/SciKit-Surgery/PythonTemplate)), -> we recommend using their template instead of this one. +> If you're making a package within a community that has an existing template we recommend using their template instead! ## Using our Python package template -Some quick instructions for using our template are below. +Here are some brief instructions if you're familiar with the command line. We also have a longer [tutorial](./tutorial.md) that has been presented in workshops for researchers at UCL. -If you have [uv] installed, you can use our template with the following command: +If you have [uv] installed, you can run the following one-liner: ```sh uvx cookiecutter gh:ucl-arc/python-tooling --checkout latest ``` -If you don't want to use uv you can [install cookiecutter] using pip, and run the above command without the leading `uvx`. +If you don't want to use uv you can [install cookiecutter], and run: -When [cookiecutter] runs, it will ask you a series of questions to configure your project. -Type the answer or hit return without typing anything to use the default option (shown in parenthesis). -At the end, it will print some more follow-up information in the terminal for things like creating a remote repository and making a website for your package. +```sh +cookiecutter gh:ucl-arc/python-tooling --checkout latest +``` + +(The same as above without the `uvx`.) + +[Cookiecutter] will ask you a series of questions to configure your project. +Type the answer, or hit return without typing anything to use the default option (shown in parenthesis). + +At the end, it prints some follow-up information to the terminal. +These are tips for things like creating a repository and making a website for your package. It will have created a directory for your project. You can see the structure with the `tree` command. In our example we've called our project `example-research-software-project`: ```sh -ls -ltr | tail -n1 # Shows the last directory that was created +ls -ltr | tail -n1 # Show the last directory that was created tree example-research-software-project ``` @@ -58,7 +59,9 @@ git init uv sync ``` -Note that `uv>=0.6.7` is required to use the `--group` option. +## Need help? + +We've turned on [discussions] for this repository, and we welcome questions there or in the `#helpme` channel on UCL's [Research Programming Hub Slack](. @@ -68,6 +71,8 @@ Note that `uv>=0.6.7` is required to use the `--group` option. [cookiecutter]: https://cookiecutter.readthedocs.io/en/stable [install cookiecutter]: https://cookiecutter.readthedocs.io/en/stable/README.html#installation [uv]: https://docs.astral.sh/uv +[discussions]: https://github.com/UCL-ARC/python-tooling/discussions +[Research Programming Hub Slack]: https://www.ucl.ac.uk/advanced-research-computing/community/ucl-research-programming-hub ## Contributors From 371f88bcc7900a401cdd4281cbd10184e91c7459 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Thu, 18 Sep 2025 14:34:19 +0100 Subject: [PATCH 2/5] More improvements. Some suggestions from copilot. --- README.md | 44 +++++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index b0f86d20..f76e5b6b 100644 --- a/README.md +++ b/README.md @@ -5,49 +5,56 @@ -This 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. +This repository collects our recommendations for a research software project in Python. +We have a [website], if you just need some advice, and a template if you're starting from scratch. -🍪 Our template uses [cookiecutter] to can create new Python packages with our preferred tools set up and ready to go. +🍪 Our template uses [cookiecutter] to set up a new package with our preferred tools ready to go. > [!NOTE] -> If you're making a package within a community that has an existing template we recommend using their template instead! +> If you're making a package in research community that already has a template, use theirs instead! -## Using our Python package template +## How to use our template -Here are some brief instructions if you're familiar with the command line. -We also have a longer [tutorial](./tutorial.md) that has been presented in workshops for researchers at UCL. +If you're comfortable with the command line, here are some quick start steps. +We also have a more detailed [tutorial](./tutorial.md) that has been presented in workshops for researchers at UCL. -If you have [uv] installed, you can run the following one-liner: +If you have [uv] installed, run: ```sh uvx cookiecutter gh:ucl-arc/python-tooling --checkout latest ``` -If you don't want to use uv you can [install cookiecutter], and run: +If you don't want to use uv you can [install cookiecutter], then run without `uvx`: ```sh cookiecutter gh:ucl-arc/python-tooling --checkout latest ``` -(The same as above without the `uvx`.) +[Cookiecutter] will ask you questions to set up your project. +Type your answer, or hit return without typing anything to use the defaults. -[Cookiecutter] will ask you a series of questions to configure your project. -Type the answer, or hit return without typing anything to use the default option (shown in parenthesis). +When finished, it prints some information to the terminal. +These are tips for next steps like creating a repository and making a website for your package. -At the end, it prints some follow-up information to the terminal. -These are tips for things like creating a repository and making a website for your package. +It will have created a directory for your project: + +```sh +ls -ltr | tail -n1 # Show the last directory that was created +``` -It will have created a directory for your project. You can see the structure with the `tree` command. In our example we've called our project `example-research-software-project`: ```sh -ls -ltr | tail -n1 # Show the last directory that was created tree example-research-software-project ``` -To work on your project, initialise a `git` repository and _install_ your new package editable mode. +To start working on your project: + +- change directory to your project directory, +- initialise a `git` repository, +- and _install_ your new package editable mode. + You probably want to do this in a [virtual environment](./docs/pages/virtual.md). The comments show how to do this in [uv] with `uv venv`: @@ -61,13 +68,12 @@ uv sync ## Need help? -We've turned on [discussions] for this repository, and we welcome questions there or in the `#helpme` channel on UCL's [Research Programming Hub Slack](. +You can ask questions in [discussions] or in the `#helpme` channel on UCL's [Research Programming Hub Slack]. [website]: https://github-pages.arc.ucl.ac.uk/python-tooling -[UCL ARC]: https://ucl.ac.uk/arc [cookiecutter]: https://cookiecutter.readthedocs.io/en/stable [install cookiecutter]: https://cookiecutter.readthedocs.io/en/stable/README.html#installation [uv]: https://docs.astral.sh/uv From c212066fc14c9044f32bcdd6c2f2e78d809e6613 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Thu, 18 Sep 2025 14:46:34 +0100 Subject: [PATCH 3/5] Typo and delete a 'just'. The Carpentries people would not be happy about 'just'. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f76e5b6b..d9e25c76 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,12 @@ This repository collects our recommendations for a research software project in Python. -We have a [website], if you just need some advice, and a template if you're starting from scratch. +We have a [website] if you need some advice, and a template if you're starting from scratch. 🍪 Our template uses [cookiecutter] to set up a new package with our preferred tools ready to go. > [!NOTE] -> If you're making a package in research community that already has a template, use theirs instead! +> If you're making a package in a research community that already has a template, use theirs instead! ## How to use our template From 523ed25376eea67d73febf0f2e86431bf086cf0b Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Wed, 8 Oct 2025 13:07:06 +0100 Subject: [PATCH 4/5] Lowercase for consistent name "cookiecutter" Overruled by Vale and @paddyroddy. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d9e25c76..76553731 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ If you don't want to use uv you can [install cookiecutter], then run without `uv cookiecutter gh:ucl-arc/python-tooling --checkout latest ``` -[Cookiecutter] will ask you questions to set up your project. +[cookiecutter] will ask you questions to set up your project. Type your answer, or hit return without typing anything to use the defaults. When finished, it prints some information to the terminal. From 67397fc9469135a5b3af9a3525d8f4e072e04ff8 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Wed, 8 Oct 2025 13:08:38 +0100 Subject: [PATCH 5/5] Ruff-compliant space before comment. Co-authored-by: Patrick J. Roddy --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 76553731..0887618f 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ These are tips for next steps like creating a repository and making a website fo It will have created a directory for your project: ```sh -ls -ltr | tail -n1 # Show the last directory that was created +ls -ltr | tail -n1 # Show the last directory that was created ``` You can see the structure with the `tree` command.