From 99792a751874d808111d7ea2bddd3f345fd92232 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Fri, 6 Jun 2025 16:52:06 +0100 Subject: [PATCH 1/7] Add `Readability` scores to `vale`. --- .vale.ini | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.vale.ini b/.vale.ini index f10a4e56..1304af53 100644 --- a/.vale.ini +++ b/.vale.ini @@ -2,12 +2,14 @@ StylesPath = .github/styles # https://github.com/errata-ai/packages Packages = proselint,\ - write-good + write-good,\ + Readability [*.md] BasedOnStyles = proselint,\ Vale,\ - write-good + write-good,\ + Readability # Disable Vale.Spelling = NO From f40943f6791e95d253ce04f9018142ee76957c1a Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 9 Jun 2025 16:10:28 +0100 Subject: [PATCH 2/7] First half. --- tutorial.md | 100 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 67 insertions(+), 33 deletions(-) diff --git a/tutorial.md b/tutorial.md index 0a45d554..d649ce69 100644 --- a/tutorial.md +++ b/tutorial.md @@ -1,41 +1,50 @@ # Tutorial: creating a package using template -In this tutorial we will go through in detail the steps required to set-up a Python package using the `UCL-ARC/python-tooling` πŸͺ cookiecutter template as well as some follow on steps illustrating how to use the newly created package with some of the included tools. +In this tutorial we will go through the steps to set-up a Python package using the `UCL-ARC/python-tooling` πŸͺ cookiecutter template. +We'll also show you how to use your new package with some of the tools included. > [!TIP] -> Some of the commands and URLs in the instructions contain placeholders within curly braces such as `{project_slug}`. You will need to replace these placeholders (including the curly braces) with the relevant values for your particular package / project - the text should give details of what should be subsituted for each placeholder. +> Some of the commands and URLs in this tutorial contain placeholders in curly braces like: `{project_slug}`. +> You'll need to replace these placeholders (including the curly braces) with the relevant values for your package or project. +> We'll always explain what should be subsituted for each placeholder. -## βš™οΈ Setting up dependencies for using template +## βš™οΈ Prerequisites for using the template
Click to expand... -To use the template you will need to install the following software tools +To use the template you'll need the following software: -- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -- [uv](https://docs.astral.sh/uv/getting-started/installation/) -- [the GitHub command line interface (CLI)](https://github.com/cli/cli?tab=readme-ov-file#installation) +- A terminal; +- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git); +- [`uv`](https://docs.astral.sh/uv/getting-started/installation/); +- and the official GitHub command line interface (CLI): [`gh`](https://github.com/cli/cli?tab=readme-ov-file#installation). -The instructions for installing these tools can be accessed by clicking the individual links above. +The instructions for installing these tools are at the individual links, above. -Additionally, [cookiecutter](https://cookiecutter.readthedocs.io) will be required to generate your package from the template, which can be installed using the instructions below. For the follow on exercises you will also need an [account set up on GitHub](https://github.com/join) if you don't already have one. +You'll also need [cookiecutter] to generate your package from the template. +If you don't have [cookiecutter], don't worry, we'll install it with `uv` in the next steps. +For the later part of the tutorial, you'll need an [account on GitHub](https://github.com/join), if you don't already have one. -An easy way to install and manage Python packages is using `uv`, which can create a dedicated environment with the necessary packages installed using the step by step instructions below +[cookiecutter]: https://cookiecutter.readthedocs.io -1. Open a terminal window +An easy way to install and manage Python packages is using `uv`. +We'll use `uv` to install [cookiecutter] in the following steps, skip step 2 if you've already got [cookiecutter]. + +1. Open a terminal - On Windows: open the Start menu from the taskbar, type `cmd` in the search field, then click [command prompt](https://en.wikipedia.org/wiki/Command-line_interface#Command_prompt) from the results. - - On MacOS: click the Launchpad icon in the Dock, type `Terminal` in the search field, then click `Terminal` from the results. - - On Linux: open the default terminal application installed in your distribution. + - On MacOS: click the Launchpad icon in the Dock, type `terminal` in the search field, then click `Terminal` from the results. + - On Linux: open the default terminal application installed in your distribution. You can usually do this with `t`. -2. In the terminal window, type +2. In the terminal, type ```sh uv tool install cookiecutter ``` - to install the "tools" necessary for creating and using a package using the `UCL-ARC/python-tooling` cookiecutter template. + and press enter, to install [cookiecutter] as a [`uv` tool](https://docs.astral.sh/uv/concepts/tools/) on your computer. -3. To check that all the dependencies have installed correctly, run each of the following commands in turn, one at a time +3. To check that everything was installed correctly, run each of the following commands, one at a time ```sh cookiecutter --version @@ -43,44 +52,55 @@ An easy way to install and manage Python packages is using `uv`, which can creat git --version ``` - For each command you should see some text outputted to the terminal giving details of the installed versions of the applications - the output itself is not important as long as you do not see any error messages. + For each command you should see some text in the terminal giving each of the versions installed. + The output itself isn't important, as long as you don't see any error messages. -4. If you also want to try out creating a GitHub repository for the package you will need to [sign-up for a free GitHub account](https://github.com/join) if you don't already have one. Once you have a GitHub account, open a terminal window - you can either use the same one as previously if you still have it open, or open a new terminal window as described in step 2 and then run +4. If you have a GitHub account then run ```sh gh auth login ``` - to authenticate the GitHub command line interface tool `gh` with your GitHub account credentials. The tool will ask you a series of question, for most of which you can select the default options by just hitting the `Enter` key. Specifically select: + to authenticate the GitHub CLI with your GitHub account. + The tool will ask you some questions, for most these you can select the default options by just hitting the `Enter` key. + + Specifically, make sure you choose: - `GitHub.com` for account to log into, - `HTTPS` for preferred protocol, - `Y` to authenticate Git with your GitHub credentials, - `Login with a web browser` as the method to authenticate. - Once you have selected all these options, a one-time code will be printed to the terminal. You need to copy this code and then hit the `Enter` key to open a page to complete the authentication in your default browser. Once you have entered and submitted the code in the authenticatication page, you should see a `Authentication complete` message appear in the terminal window. + Once you've done this, a one-time code will be printed to the terminal. + Copy this code and then hit the `Enter` key to open a web browser and complete the authentication. + Once you've finished in the browser window, you should see an `Authentication complete` message appear in the terminal window.
## πŸͺ Creating a package using the template -We will first go through the steps for creating a new package using the `UCL-ARC/python-tooling` cookiecutter template. +We'll first go through creating a new package using the `UCL-ARC/python-tooling` template. -1. Open a new terminal/command prompt window and change the working directory to the path you wish to create the package in using the `cd` (change directory) command +1. Open a new terminal and change the working directory to where you want to create the package. ```sh cd path/to/directory ``` -2. To begin creating the package run +2. To create the package run ```sh cookiecutter gh:ucl-arc/python-tooling --checkout latest ``` - You will then be shown a series of prompts at the command line asking for details of the project and package. You can choose to use the default placeholder value (shown in parenthesis `()` in prompt) for any question by hitting `Enter`. If you already have a specific project in mind you want to set up a package for using the template you can use this project's details, otherwise you can just use the placeholder values. You should choose `Y` (yes) to the questions on whether to initialise Git repository and automatically deploy HTML documentation to GitHub Pages to allow you to complete the follow on exercises which rely on these options being enabled. For the prompt asking for the GitHub user or organization name to be owner of repository you should supply your GitHub user name. + You will be shown a series of prompts asking for details of the project and package. + You can choose to use the default value (shown in parenthesis `()` in prompt) for any question by hitting `Enter`. + If you already have a specific project in mind you can use this project's details, otherwise use the placeholder values. + You should choose `Y` (yes) to the questions on whether to initialise a Git repository and automatically deploy HTML documentation to GitHub Pages (this is used in a later section). + When you're asked for the `GitHub user or organisation ...` type your GitHub username. -3. Once you have completed all the cookiecutter prompts some additional instructions will be printed to screen (which we will come back to in the next sections) and your new package will be generated in a directory named `{project_slug}` in the current working directory (where `{project_slug}` is the value entered for the `'Slugified' project name...`[^slug] prompt, this will be `python-template` if you used the default placeholder values). You can see the directory tree of files generated by running +3. Once you have answered all of the questions, some additional instructions will be printed to screen (we will come back to these later). + Your new package is in a directory named `{project_slug}` in the current working directory (where `{project_slug}` is the value entered for the `'Slugified' project name...`[^slug] prompt, this will be `python-template` if you used the default placeholder values). You can see the directory tree of files generated by running ```sh tree {project_slug} @@ -121,7 +141,9 @@ We will first go through the steps for creating a new package using the `UCL-ARC The package you created in the previous section will have been initialised locally as a Git repository (providing you answered 'Y' to the relevant prompt!) to allow keeping the package under version control, but some extra steps are required to have the local repository synchronised to a remote repository on [GitHub](https://github.com/). The advantages of doing this are that makes it easy for other people to both download and use the package but also contribute to your project. The package has also been set up to take advantage of GitHub's continuous integration and deployment service [GitHub Actions](https://docs.github.com/en/actions) (which is free to use for public repositories) with workflows included for automatically running the package tests, performing [linting checks]() and building the project documentation, on every [pull-request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) and on updates to the default `main` [branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) for the repository. -When you completed setting up the package using the `cookiecutter` command you should have seen some additional instructions printed to screen including, providing you have the [GitHub CLI](https://cli.github.com/) `gh` installed, a message of the form +When you've finished answering questions the you should see some additional instructions printed to screen. + +If you have the [GitHub CLI](https://cli.github.com/) `gh` installed, you should see: ```sh GitHub CLI detected, you can create a repo with the following: @@ -129,11 +151,14 @@ GitHub CLI detected, you can create a repo with the following: gh repo create {github_owner}/{project_slug} -d "{project_description}" --public -r origin --source {project_slug} ``` -where `{github_owner}`, `{project_slug}` and `{project_description}` are replaced with the relevant GitHub repository owner (user name), project slug and description that you entered when setting up the package using `cookiecutter`. You should now copy-paste and run the `gh repo create ...` command that was printed out in the message - if you no longer have access to the message you can use the example above, being careful to subsitute the placeholders in braces `{}` with the relevant values. +where `{github_owner}`, `{project_slug}` and `{project_description}` are replaced with your username and your project name. +package. +You should copy-paste and run the `gh repo create ...` command, +If you closed your terminal or longer have access to the message for some reason, you can use the example above being careful to subsitute the placeholders in braces `{}`. -If you get an error message at this point it may be because you have not installed the GitHub CLI or set up the authorisation for the GitHub CLI as [described in the setup instructions above](#%EF%B8%8F-setting-up-dependencies-for-using-template). +If you get an error message at this point it may be because you have not installed `gh` or set up authorisation as [described in the setup instructions above](#️-prerequisites-for-using-the-template). -If the command runs successfully you should see a message of the form +If the command worked you should see a message something like: ```sh βœ“ Created repository {github_owner}/{project_slug} on GitHub @@ -141,9 +166,17 @@ If the command runs successfully you should see a message of the form βœ“ Added remote https://github.com/{github_owner}/{project_slug}.git ``` -A repository should have been created at the printed URL which you should be able to navigate to in your browser (either copy-paste in to browser or depending on terminal application you may be able to hold `Ctrl` and click on URL directly). Currently both the remote and local repositories are empty as we have not made any commits. +A repository will have been created at the URL (the one which doesn't end in `.git`). +You should be able to go there in your browser (either copy-paste into a browser or --depending on your terminal-- you may be able to hold `Ctrl` and click on URL directly). +Keep the browser window open for now, but return to the terminal. + +> [!TIP] +> Your computer has a _*local*_ copy of this repository and GitHub has a _*remote*_ copy. + +At the moment, both the remote and local repositories are empty as we have not made any commits. -To commit the package files generated by `cookiecutter` locally on the default `main` branch and also push this commit to the repository on GitHub, run each of the commands below in turn, replacing the `{project_slug}` placeholder with the relevant value you used when creating package (`python-template` if you used default) +To commit the package files generated by `cookiecutter`, and also push this commit to the repository on GitHub, run each of the commands below in turn. +You'll need to replace `{project_slug}` with your package name. ```sh cd {project_slug} @@ -152,7 +185,8 @@ git commit -m "Initial commit" git push --set-upstream origin main ``` -If you now navigate to the GitHub repository URL in your browser you should see the package files present, with the content of the top-level `README.md` being displayed as the repository landing page. +If you go back to your browser and refresh, you should see the package files appear. +You should also see the top-level `README.md` displayed as the repository landing page. The push of the initial commit to the default `main` branch will have also triggered runs of the GitHub Actions workflows set up in the repository. You can view the status of the workflow job runs by opening the `Actions` pane from the top navigation bar on the repository landing page, or going to the URL `https://github.com/{github_owner}/{project_slug}/actions`. @@ -198,7 +232,7 @@ The index page of the documentation reproduces the content from the repository R It is recommended to set up a project-specific [virtual environment](https://docs.python.org/3/tutorial/venv.html) whenever working on Python project. This allows you to install the versions of third-party packages the project requires without conflicting with the requirements of other projects you are developing. -There are a variety of virtual environment management tools available for Python. One option is [uv](https://docs.astral.sh/uv), which you will have installed if you followed our detailed set-up instructions above, or may already have installed previously. `uv` is an extremely fast Python package and virtual environment manager that has API compatiblility with `pip` and the built-in virtual environment manager - [`venv`](https://docs.python.org/3/library/venv.html). +There are a lot of virtual environment management tools available for Python. One option is [uv](https://docs.astral.sh/uv), which you will have installed if you followed our detailed set-up instructions above, or may already have installed previously. `uv` is an extremely fast Python package and virtual environment manager that has API compatiblility with `pip` and the built-in virtual environment manager - [`venv`](https://docs.python.org/3/library/venv.html). Once you are in your `{project_slug}` directory, a virtual environment can be created by running the following in a terminal/command prompt window From e493874ce10458060258e04a01a72275b48db034 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 14 Jul 2025 11:35:53 +0100 Subject: [PATCH 3/7] Second half. --- tutorial.md | 160 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 116 insertions(+), 44 deletions(-) diff --git a/tutorial.md b/tutorial.md index d649ce69..507f7d0e 100644 --- a/tutorial.md +++ b/tutorial.md @@ -1,12 +1,12 @@ -# Tutorial: creating a package using template +# Tutorial: creating a package using our template -In this tutorial we will go through the steps to set-up a Python package using the `UCL-ARC/python-tooling` πŸͺ cookiecutter template. +In this tutorial, we will go through the steps to set up a Python package using the `UCL-ARC/python-tooling` πŸͺ cookiecutter template. We'll also show you how to use your new package with some of the tools included. > [!TIP] > Some of the commands and URLs in this tutorial contain placeholders in curly braces like: `{project_slug}`. > You'll need to replace these placeholders (including the curly braces) with the relevant values for your package or project. -> We'll always explain what should be subsituted for each placeholder. +> We'll always explain what should be substituted for each placeholder. ## βš™οΈ Prerequisites for using the template @@ -87,19 +87,19 @@ We'll first go through creating a new package using the `UCL-ARC/python-tooling` cd path/to/directory ``` -2. To create the package run +2. To create the package, run ```sh cookiecutter gh:ucl-arc/python-tooling --checkout latest ``` You will be shown a series of prompts asking for details of the project and package. - You can choose to use the default value (shown in parenthesis `()` in prompt) for any question by hitting `Enter`. - If you already have a specific project in mind you can use this project's details, otherwise use the placeholder values. + You can choose to use the default value (shown in parentheses `()` in the prompt) for any question by hitting `Enter`. + If you already have a specific project in mind, you can use this project's details; otherwise, use the placeholder values. You should choose `Y` (yes) to the questions on whether to initialise a Git repository and automatically deploy HTML documentation to GitHub Pages (this is used in a later section). When you're asked for the `GitHub user or organisation ...` type your GitHub username. -3. Once you have answered all of the questions, some additional instructions will be printed to screen (we will come back to these later). +3. Once you have answered all of the questions, some additional instructions will be printed to the terminal (we will come back to these later). Your new package is in a directory named `{project_slug}` in the current working directory (where `{project_slug}` is the value entered for the `'Slugified' project name...`[^slug] prompt, this will be `python-template` if you used the default placeholder values). You can see the directory tree of files generated by running ```sh @@ -112,14 +112,14 @@ We'll first go through creating a new package using the `UCL-ARC/python-tooling` tree /F {project_slug} ``` - in both cases replacing `{project_slug}` with the relevant value you used (`python-template` if you used the default values). - Some of the key files and directories are + in both cases, replacing `{project_slug}` with the name you used (`python-template` if you used the default). + Some of the key files and directories are: - - The `README.md` file which is a Markdown file describing the project and acting as a landing page for first-time users. - - The `LICENSE.md` file which contains the terms of the open-source license the code is released under. - - The `src` directory which will contain the Python package source code. - - The `docs` directory which will contain the Markdown files used to generate the documentation pages for the package. - - The `tests` directory which will contain the Python modules defining tests to check for the correctness of the package code. + - The `README.md` file is a Markdown file describing the project and acting as a landing page for first-time users. + - The `LICENSE.md` file contains the terms of the open-source license the code is released under. + - The `src` directory, which will contain the Python package source code. + - The `docs` directory, which will contain the Markdown files used to generate the documentation pages for the package. + - The `tests` directory, which will contain the Python modules defining tests to check for the correctness of the package code. Try viewing the content of some of the files generated by running @@ -135,11 +135,11 @@ We'll first go through creating a new package using the `UCL-ARC/python-tooling` on Windows, replacing `{path_to_file}` with the relevant path. -[^slug]: A ['slug'](https://en.wikipedia.org/wiki/Clean_URL#Slug) in this context is a human readable identifier with words typically separated by hyphens that can be used as part of a URL. +[^slug]: A ['slug'](https://en.wikipedia.org/wiki/Clean_URL#Slug) in this context is a human-readable identifier with words typically separated by hyphens that can be used as part of a URL. ## πŸ“¦ Creating a repository on GitHub for the new package -The package you created in the previous section will have been initialised locally as a Git repository (providing you answered 'Y' to the relevant prompt!) to allow keeping the package under version control, but some extra steps are required to have the local repository synchronised to a remote repository on [GitHub](https://github.com/). The advantages of doing this are that makes it easy for other people to both download and use the package but also contribute to your project. The package has also been set up to take advantage of GitHub's continuous integration and deployment service [GitHub Actions](https://docs.github.com/en/actions) (which is free to use for public repositories) with workflows included for automatically running the package tests, performing [linting checks]() and building the project documentation, on every [pull-request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) and on updates to the default `main` [branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) for the repository. +The package you created in the previous section will have been initialised locally as a Git repository (providing you answered 'Y' to the relevant prompt!) to allow keeping the package under version control, but some extra steps are required to have the local repository synchronised to a remote repository on [GitHub](https://github.com/). The advantages of doing this are that it makes it easy for other people to both download and use the package but also contribute to your project. The package has also been set up to take advantage of GitHub's continuous integration and deployment service [GitHub Actions](https://docs.github.com/en/actions) (which is free to use for public repositories) with workflows included for automatically running the package tests, performing [linting checks]() and building the project documentation, on every [pull-request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) and on updates to the default `main` [branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) for the repository. When you've finished answering questions the you should see some additional instructions printed to screen. @@ -154,7 +154,7 @@ gh repo create {github_owner}/{project_slug} -d "{project_description}" --public where `{github_owner}`, `{project_slug}` and `{project_description}` are replaced with your username and your project name. package. You should copy-paste and run the `gh repo create ...` command, -If you closed your terminal or longer have access to the message for some reason, you can use the example above being careful to subsitute the placeholders in braces `{}`. +If you closed your terminal or longer have access to the message for some reason, you can use the example above being careful to substitute the placeholders in braces `{}`. If you get an error message at this point it may be because you have not installed `gh` or set up authorisation as [described in the setup instructions above](#️-prerequisites-for-using-the-template). @@ -188,13 +188,21 @@ git push --set-upstream origin main If you go back to your browser and refresh, you should see the package files appear. You should also see the top-level `README.md` displayed as the repository landing page. -The push of the initial commit to the default `main` branch will have also triggered runs of the GitHub Actions workflows set up in the repository. You can view the status of the workflow job runs by opening the `Actions` pane from the top navigation bar on the repository landing page, or going to the URL `https://github.com/{github_owner}/{project_slug}/actions`. +When you pushed to `main` you will have triggered runs of the [GitHub actions](https://docs.github.com/en/actions/about-github-actions/understanding-github-actions) workflows that are included in the template. +You can view the status of the workflow jobs by browsing the `Actions` button at the top bar of the repository homepage, which takes you to `https://github.com/{github_owner}/{project_slug}/actions`. -Depending on your account settings, you may find that the `Documentation` workflow shows as failed (❌). If this is the case this is likely because the repository has been set by default to only allow GitHub Actions workflows read permissions on the repository, which prevents the step in the `Documentation` workflow which pushes the built HTML documentation to a branch `gh-pages` from completing. In the next section we will look at how to configure the repository to ensure the permissions are set correctly and have the HTML documentation deployed to a GitHub Pages website. +Depending on your account settings, you may find that the `Documentation` workflow shows as failed (❌). +If you see this it's probably because of the repository permissions settings for GitHub Actions. +We'll fix this in the next section. + +For now, have a browse around the GitHub web interface. ## πŸ“„ Configuring repository to host docs on GitHub Pages -Now that the repository is synchronised to GitHub, a few additional steps are required to configure the repository for the HTML documentation to be automatically deployed to [GitHub Pages](https://pages.github.com/). On completion of the `cookiecutter` command to create the package, a message of the form below should have been displayed +Now that your repository is on GitHub, you need to do a few more steps to set up your project's documentation website. +The HTML documentation will be built using the `Documentation` workflow (that we're going to fix) and hosted on [GitHub Pages](pages.github.com/). + +If you scroll back in your terminal to the end of the [cookiecutter] questions, you should be able to find a message like: ```sh The 'Documentation' GitHub Actions workflow has been set up to push the built @@ -216,48 +224,79 @@ and under 'Built and deployment' selecting 'Deploy from a branch' for the branch path drop-down with its default value of '/ (root)'. ``` -where as before `{github_owner}` and `{project_slug}` are replaced with the relevant GitHub repository owner and project slug that you entered when setting up the package. +As before replace `{github_owner}` and `{project_slug}` with the relevant GitHub repository owner and project slug that you chose at the start. + +The first part of the instructions explains how to set the permissions for GitHub Actions. +This lets the Actions bot push the built HTML documentation to a branch `gh-pages` when you update the default `main` branch. + +- Go to the Actions settings page at the URL above (or via the repository `Settings` tab, then `Actions > General`). +- Set `Workflow permissions` to `Read and write permissions`. + +Now that the permissions have changed, we need to re-run the `Documentation` workflow. + +- Go back to the Actions page. Select the Actions button (in the top bar), or visit + `https://github.com/{github_owner}/{project_slug}/actions`. +- Click on the failing entry for the `Documentation` workflow. +- Click on the `Re-run all jobs` button (top right of the page). -The first part of the instructions gives details of how to set the permissions for GitHub Actions workflows in the repository to allow the GitHub Actions bot to push the built HTML documentation to a branch `gh-pages` on updates to the default `main` branch on the repository, so that the documentation is automatically updated whenever changes are merged in to `main`. After going to the Actions settings page at the URL indicated (which can also be reached by going to the `Settings` tab in the top navigation bar of the repository and then selecting `Action > General` in the left hand navigation menu) and ensuring `Workflow permissions` is set to allow `Read and write permissions`, if you have changed the permissions you will also need to re-run the documentation workflow with the updated permissions. This can be done by going to the Actions pane in the repository (accessible from top navigation bar or by going to `https://github.com/{github_owner}/{project_slug}/actions`), clicking on the (top / latest if there are multiple) entry for the _Documentation_ workflow, which should be showing as failing, and then from the resulting page click the `Re-run all jobs` button. +After the `Documentation` workflow finishes, a new `gh-pages` branch will be created containing only the HTML docs. -Once the _Documentation_ workflow has successfully completed, a new branch `gh-pages` should have been created in the repository containing the HTML documentation. The second part of the instructions printed in the message output by the `cookiecutter` command indicate to go to a URL `https://github.com/{github_owner}/{project_slug}/settings/pages` to set this branch as the source for a GitHub Pages website for the repository. If you now follow those instructions, setting the `Source` to `Deploy from branch` and `Branch` to `gh-pages`, the a new Actions workflow `pages-build-deployment` will be automatically triggered. Once this workflow has completed, you should be able to view the HTML documentation for the repository at a URL +Following tha instructions printed to the terminal, go to `https://github.com/{github_owner}/{project_slug}/settings/pages` and set this branch as the source for GitHub Pages. + +- Set `Source` to `Deploy from branch` and `Branch` to `gh-pages`. + +This will start another new workflow called `pages-build-deployment` (in the Actions page). +When it finishes, you can view your HTML docs at: ```sh https://{github_owner}.github.io/{project_slug} ``` -The index page of the documentation reproduces the content from the repository README file. The documentation site also importantly includes _application programming interface_ (API) reference documentation built from the [docstrings](https://peps.python.org/pep-0257/#what-is-a-docstring) in the package source code; this API documentation is accessible from the `API reference` link in the navigation. +πŸŽ‰ + +You should see that the homepage of the documentation site is the same as the repository README file. +Importantly, the documentation website inclides the [_application programming interface_ (API](https://en.wikipedia.org/wiki/API) reference documentation. +The API documentation is generated from [docstrings](https://peps.python.org/pep-0257/#what-is-a-docstring) in the source code. ## 🐍 Setting up a virtual environment for project -It is recommended to set up a project-specific [virtual environment](https://docs.python.org/3/tutorial/venv.html) whenever working on Python project. This allows you to install the versions of third-party packages the project requires without conflicting with the requirements of other projects you are developing. +We recommend setting up a project-specific [virtual environment](https://docs.python.org/3/tutorial/venv.html) for each of your Python projects. +This means you can install the specific versions of third-party packages that each project requires without conflicting with the requirements of your other projects. -There are a lot of virtual environment management tools available for Python. One option is [uv](https://docs.astral.sh/uv), which you will have installed if you followed our detailed set-up instructions above, or may already have installed previously. `uv` is an extremely fast Python package and virtual environment manager that has API compatiblility with `pip` and the built-in virtual environment manager - [`venv`](https://docs.python.org/3/library/venv.html). +There are a lot of virtual environment management tools available for Python. +One option is [uv](https://docs.astral.sh/uv), which you will have installed if you followed our detailed set-up instructions above, or may already have installed previously. +`uv` is an extremely fast Python package and virtual environment manager that uses the familiar `pip` and [`venv`](https://docs.python.org/3/library/venv.html) commands (`venv` is the built-in virtual environment manager that comes with Python). -Once you are in your `{project_slug}` directory, a virtual environment can be created by running the following in a terminal/command prompt window +Back in the terminal, and from your `{project_slug}` directory, you can create a virtual environment by running: ```sh -uv venv .venv +uv venv ``` -This will create a new environment with name `.venv`, which can be activated for installing packages using +This will create a new environment in the hidden `.venv` directory. +`uv` tells you how to activate the environment: ```sh source .venv/bin/activate ``` -or if on Windows +or on Windows: ```sh .venv\Scripts\activate ``` -You should see `(.venv)` on the left of your terminal window. Once you have activated the environment you can use the following command to install any packages within the `.venv` environment +So activate your environment and you should see braces `( )` with your project slug on the left of your terminal window. +This might be slightly different depending on your terminal setup. + +Once you have activated the environment you can use the following command to install any packages within the `.venv` environment ```sh uv pip install numpy ``` +(We're using `numpy` as an example.) + The environment can be deactivated using ```sh @@ -283,7 +322,7 @@ from the root of the project repository. Alternatively, you can use the [`venv` module](https://docs.python.org/3/library/venv.html), which is slower and has fewer features, when compared to `uv`, but is built-in to the Python standard library. `venv` has the advantage of being available in any Python (3.3+) environment, but unlike `uv` will not by itself allow you to use a different Python version from the system level install. A common pattern is to store the virtual environment files in a directory `.venv` within the root directory of the project repository. This can be achieved by running ```sh -python -m venv .venv +python -m venv ``` from the root of the project repository. To activate the new virtual environment, if on Linux or MacOS run from the root of the project repository @@ -298,13 +337,13 @@ or if on Windows .venv\Scripts\activate ``` -Once you have activated the environment you should make sure the version of the Python package manager `pip` installed in the environment is up to date by running +Once you've activated the environment you can make sure the version of the Python package manager `pip` installed in the environment is up to date: ```sh python -m pip install --upgrade pip ``` -Similar to `uv`, once the environment is active, you can install the package in editable mode, along with both its required dependencies and optional sets of dependencies by running +Similar to `uv`, once the environment is active, you can install the package in editable mode as well as all dependencies: ```sh python -m pip install --editable ".[dev,docs,test]" @@ -314,7 +353,10 @@ python -m pip install --editable ".[dev,docs,test]" ## πŸ§ͺ Running package tests locally -The package template includes support for running tests using the [`pytest` testing framework](https://docs.pytest.org/). Tests are defined in modules in the `tests` directory. By default a single test module `tests/test_dummy.py` is created with a placeholder test. You can run the test locally using `pytest` directly (you will need to have the virtual environment active in which you installed the package and its dependencies) by running +The package template includes support for running tests using the [`pytest` testing framework](https://docs.pytest.org/). +Tests are defined in the `tests` directory. +By default a single test module `tests/test_dummy.py` is created with a placeholder test. +You can run the tests locally using `pytest` in your virtual environment: ```sh pytest @@ -322,7 +364,11 @@ pytest from the root of the project repository. -The package template also sets up [`tox`](https://tox.wiki), an automation tool which allows easily running tests in isolated environments and under multiple Python versions. You can run the tests across all compatible Python versions currently installed using `tox` by running +The package template also sets up [`tox`](https://tox.wiki). +`tox` is a tool which allows you to easily run tests in isolated environments under different Python versions. +These tests don't interfere with the virtual environment that you use for developing the code. + +You can run the tests across _all compatible Python versions currently installed_ using `tox` by running ```sh tox @@ -332,36 +378,62 @@ from the root of the project repository. ## πŸ“– Building documentation locally -It can sometimes be useful when editing docstrings or adding additional pages in the `docs` directory to be able to render the HTML documentation locally. The package is set up to use [MkDocs](https://www.mkdocs.org/) to build the documentation with the package API documentation generated using the [`mkdocstrings` plug-in](https://mkdocstrings.github.io/). These packages will have been installed in to you local development environment providing you installed the package with optional `docs` dependencies as recommended above. To build and serve the documentation locally run +It's sometimes useful to be able to render the HTML documentation pages locally. +For example if you're editing docstrings or adding additional pages, and you want to check everything worked. +The package is set up to use [MkDocs](https://www.mkdocs.org/) to build the documentation website. +The API documentation is generated using the [`mkdocstrings` plug-in](https://mkdocstrings.github.io/). +Mkdocks and `mkdocstrings` will have been installed in your local development environment, because you installed the package with the `docs` dependencies. + +To build and serve the documentation locally run: ```sh mkdocs serve ``` -from the root of the project repository and navigate to `http://127.0.0.1:8000/` in your browser. The development server used here supports auto-reloading, meaning the content will be automatically refreshed in your browser if you make any edits to source. +from the root of the project repository and navigate to `http://127.0.0.1:8000/` in your browser. +The development server supports _auto-reloading_, meaning the content will be automatically refreshed in your browser if you make any edits to the docstrings or README.md. -A `tox` environment `docs` to build the documentation is also available. This will be build the documentation in an isolated environment and is also used for building the documentation in the GitHub Actions _Documentation_ workflow so can be useful to run locally when debugging issues with the workflow - it can be executed by running +There's also a `tox` environment called `docs`. +This is another way to build the documentation but in an isolated environment. +It is the command that is run in GitHub actions to build and publish the on the web (in the `Documentation` workflow). +This might be useful if debugging the Actions build, or if you didn't install the `docs` dependencies into your virtual environment. + +Run: ```sh tox -e docs ``` -from the root of the project repository. The built documentation will be output to a directory `site`. +from the root of the project repository. +The built documentation will be output to a directory `site`. ## βœ… Using `pre-commit` to run checks when committing -The package is set-up to use [pre-commit](https://pre-commit.com/), a framework for running [Git hook scripts](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) on each commit to the repository. In particular the a `.pre-commit-config.yaml` configuration file is provided which will run a series of linters, checks and formatters on the repository such as [ruff](https://docs.astral.sh/ruff/), [mypy](https://mypy.readthedocs.io/en/stable/) and [prettier](https://prettier.io/) on every commit. These Git hook scripts can installed locally by running +The package is set-up to use [pre-commit](https://pre-commit.com/), a framework for running [Git hook scripts](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) on each commit to the repository. + +There is a `.pre-commit-config.yaml` configuration file which you can take a look at. +With this setup `pre-commit` will run a series of fast linters, checks and formatters on the repository on every commit. + +The main tools we recommend are [ruff](https://docs.astral.sh/ruff/), [mypy](https://mypy.readthedocs.io/en/stable/) and [prettier](https://prettier.io/). +These Git hook scripts can installed locally by running ```sh pre-commit install ``` -from the root of the project repository. Once installed the hook scripts will be called to inspect the changes each time `git commit` is run, with any failures of the checks needing to be resolved before the changes can be commited. Some of the `pre-commit` hooks include support for auto-fixing some problems - in this case you will be alerted that a file has been changed by a hook and these changes need to be staged using `git add` before recommitting. +from the root of the project repository. +You will only need to do this once per `git clone` of the code. -The `pre-commit` hooks can be run against all files in the repository by running +Once installed, the scripts will be called to inspect the changes each time `git commit` is run. +Any failures of the checks will need to be fixed before the changes can be committed. +Some of the `pre-commit` hooks include support for auto-fixing easy problems - in this case you will be alerted that a file has been changed by a hook and these changes need to be staged using `git add` before recommitting. + +The hooks typically only run on the files _changed_ in a commit. +The `pre-commit` hooks can be run against _all files in the repository_ by running ```sh pre-commit run --all-files ``` -from the root of the project repository. As the hooks are typically only run on the files changed in a commit, this can be useful to check the hooks will pass on all files when the `pre-commit` configuration is updated by, for example, [adding a new plug-in](https://pre-commit.com/#plugins). +from the root of the project repository. +This is useful to check they will pass if the `pre-commit` configuration is updated, for example, when [adding a new plug-in](https://pre-commit.com/#plugins). From 1e447cb3b59ce8a27ebca0d8c2187566629c976f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 14 Jul 2025 10:40:43 +0000 Subject: [PATCH 4/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- tutorial.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/tutorial.md b/tutorial.md index 507f7d0e..bed22a8e 100644 --- a/tutorial.md +++ b/tutorial.md @@ -31,7 +31,6 @@ An easy way to install and manage Python packages is using `uv`. We'll use `uv` to install [cookiecutter] in the following steps, skip step 2 if you've already got [cookiecutter]. 1. Open a terminal - - On Windows: open the Start menu from the taskbar, type `cmd` in the search field, then click [command prompt](https://en.wikipedia.org/wiki/Command-line_interface#Command_prompt) from the results. - On MacOS: click the Launchpad icon in the Dock, type `terminal` in the search field, then click `Terminal` from the results. - On Linux: open the default terminal application installed in your distribution. You can usually do this with `t`. @@ -65,7 +64,6 @@ We'll use `uv` to install [cookiecutter] in the following steps, skip step 2 if The tool will ask you some questions, for most these you can select the default options by just hitting the `Enter` key. Specifically, make sure you choose: - - `GitHub.com` for account to log into, - `HTTPS` for preferred protocol, - `Y` to authenticate Git with your GitHub credentials, @@ -114,7 +112,6 @@ We'll first go through creating a new package using the `UCL-ARC/python-tooling` in both cases, replacing `{project_slug}` with the name you used (`python-template` if you used the default). Some of the key files and directories are: - - The `README.md` file is a Markdown file describing the project and acting as a landing page for first-time users. - The `LICENSE.md` file contains the terms of the open-source license the code is released under. - The `src` directory, which will contain the Python package source code. From d474564a65635c72e2ac73ba42056b781ef55410 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 14 Jul 2025 11:44:10 +0100 Subject: [PATCH 5/7] New prettier version? --- tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial.md b/tutorial.md index bed22a8e..1d25bcbb 100644 --- a/tutorial.md +++ b/tutorial.md @@ -197,7 +197,7 @@ For now, have a browse around the GitHub web interface. ## πŸ“„ Configuring repository to host docs on GitHub Pages Now that your repository is on GitHub, you need to do a few more steps to set up your project's documentation website. -The HTML documentation will be built using the `Documentation` workflow (that we're going to fix) and hosted on [GitHub Pages](pages.github.com/). +The HTML documentation will be built using the `Documentation` workflow (that we're going to fix) and hosted on [GitHub Pages](https://pages.github.com/). If you scroll back in your terminal to the end of the [cookiecutter] questions, you should be able to find a message like: From 60df8d8e57b218bd998775d896a19249aefe2551 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 14 Jul 2025 11:55:34 +0100 Subject: [PATCH 6/7] Some typos spotted by Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- tutorial.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tutorial.md b/tutorial.md index 1d25bcbb..9e6f5142 100644 --- a/tutorial.md +++ b/tutorial.md @@ -252,7 +252,7 @@ https://{github_owner}.github.io/{project_slug} πŸŽ‰ You should see that the homepage of the documentation site is the same as the repository README file. -Importantly, the documentation website inclides the [_application programming interface_ (API](https://en.wikipedia.org/wiki/API) reference documentation. +Importantly, the documentation website includes the [_application programming interface_ (API](https://en.wikipedia.org/wiki/API) reference documentation. The API documentation is generated from [docstrings](https://peps.python.org/pep-0257/#what-is-a-docstring) in the source code. ## 🐍 Setting up a virtual environment for project @@ -283,7 +283,7 @@ or on Windows: .venv\Scripts\activate ``` -So activate your environment and you should see braces `( )` with your project slug on the left of your terminal window. +Activate your environment, and you should see braces `( )` with your project slug on the left of your terminal window. This might be slightly different depending on your terminal setup. Once you have activated the environment you can use the following command to install any packages within the `.venv` environment @@ -379,7 +379,7 @@ It's sometimes useful to be able to render the HTML documentation pages locally. For example if you're editing docstrings or adding additional pages, and you want to check everything worked. The package is set up to use [MkDocs](https://www.mkdocs.org/) to build the documentation website. The API documentation is generated using the [`mkdocstrings` plug-in](https://mkdocstrings.github.io/). -Mkdocks and `mkdocstrings` will have been installed in your local development environment, because you installed the package with the `docs` dependencies. +MkDocs and `mkdocstrings` will have been installed in your local development environment, because you installed the package with the `docs` dependencies. To build and serve the documentation locally run: From 34ccbf95ff95c58612fba4d9c22268e43e87e4d0 Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Mon, 14 Jul 2025 22:34:08 +0100 Subject: [PATCH 7/7] =?UTF-8?q?Use=20=E2=80=A6=20instead=20of=20...=20as?= =?UTF-8?q?=20suggested=20by=20valse?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial.md b/tutorial.md index 9e6f5142..f4c2ee78 100644 --- a/tutorial.md +++ b/tutorial.md @@ -10,7 +10,7 @@ We'll also show you how to use your new package with some of the tools included. ## βš™οΈ Prerequisites for using the template -
Click to expand... +
Click to expand… To use the template you'll need the following software: