diff --git a/README.md b/README.md index 36521a78..0887618f 100644 --- a/README.md +++ b/README.md @@ -5,48 +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. 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 our recommendations for a research software project in Python. +We have a [website] if you need some advice, and a template if you're starting from scratch. -🍪 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 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 -> 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 in a research community that already has a template, use theirs instead! -## Using our Python package template +## How to use our template -Some quick instructions for using our template are below. -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 use our template with the following command: +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] using pip, and run the above command without the leading `uvx`. +If you don't want to use uv you can [install cookiecutter], then run without `uvx`: -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 +``` + +[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. +These are tips for next steps 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 # Shows 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`: @@ -58,16 +66,19 @@ git init uv sync ``` -Note that `uv>=0.6.7` is required to use the `--group` option. +## Need help? + +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 +[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