From 2ac3c9d344a0881b1683f239f50bf485204e0888 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Mon, 2 Feb 2026 11:28:34 +0000 Subject: [PATCH 1/5] Move tutorial under docs/pages --- tutorial.md => docs/pages/tutorial.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename tutorial.md => docs/pages/tutorial.md (100%) diff --git a/tutorial.md b/docs/pages/tutorial.md similarity index 100% rename from tutorial.md rename to docs/pages/tutorial.md From c46179e0559f777cc021dc1a5bcc796884e8c955 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Mon, 2 Feb 2026 12:02:16 +0000 Subject: [PATCH 2/5] Add Jekyll plugin for GFM admonitions --- docs/Gemfile | 1 + docs/Gemfile.lock | 7 +++++++ docs/_config.yml | 3 +++ 3 files changed, 11 insertions(+) diff --git a/docs/Gemfile b/docs/Gemfile index 5b4c4eaa..de24d141 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -4,4 +4,5 @@ gem 'jekyll', '~>4' group :jekyll_plugins do gem 'just-the-docs','~>0' + gem 'jekyll-gfm-admonitions' end diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index b84964bd..a35a0e86 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -7,6 +7,7 @@ GEM bigdecimal (3.1.9) colorator (1.1.0) concurrent-ruby (1.3.5) + cssminify (1.0.2) csv (3.3.4) em-websocket (0.5.3) eventmachine (>= 0.12.9) @@ -64,6 +65,10 @@ GEM safe_yaml (~> 1.0) terminal-table (>= 1.8, < 4.0) webrick (~> 1.7) + jekyll-gfm-admonitions (1.2.0) + cssminify (~> 1.0) + jekyll (>= 3.0, < 5.0) + octicons (~> 19.8) jekyll-include-cache (0.2.1) jekyll (>= 3.7, < 5.0) jekyll-sass-converter (3.1.0) @@ -87,6 +92,7 @@ GEM rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) mercenary (0.4.0) + octicons (19.21.2) pathutil (0.16.2) forwardable-extended (~> 2.6) public_suffix (6.0.2) @@ -166,6 +172,7 @@ PLATFORMS DEPENDENCIES jekyll (~> 4) + jekyll-gfm-admonitions just-the-docs (~> 0) BUNDLED WITH diff --git a/docs/_config.yml b/docs/_config.yml index b1c4206e..06cd169b 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -13,3 +13,6 @@ aux_links: aux_links_new_tab: true logo: "https://raw.githubusercontent.com/UCL-ARC/python-tooling/main/images/logo.svg" + +plugins: + - jekyll-gfm-admonitions From 5bd780ac9556c087602f7f5ec17127b52adf8a5f Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Mon, 2 Feb 2026 12:06:00 +0000 Subject: [PATCH 3/5] YAML front matter in tutorial plus make collapsibles render properly --- docs/pages/tutorial.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/pages/tutorial.md b/docs/pages/tutorial.md index b01ce2ca..f9a51cc4 100644 --- a/docs/pages/tutorial.md +++ b/docs/pages/tutorial.md @@ -1,4 +1,10 @@ -# Tutorial: creating a package using our template +--- +title: Template tutorial +layout: default +nav_order: 2 +--- + +## 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. We'll also show you how to use your new package with some of the tools included. @@ -10,7 +16,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: @@ -298,7 +304,7 @@ uv sync --all-groups from the root of the project repository. Note that `uv>=0.6.7` is required to use the `--group` option. -
Using venv as an alternative to uv +
Using venv as an alternative to uv 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 From 29e578e610b4c7a34fa1491a930fa98f86bc25ac Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Mon, 2 Feb 2026 12:08:51 +0000 Subject: [PATCH 4/5] Update internal links to tutorial and nav ordering --- README.md | 2 +- docs/index.md | 1 + docs/pages/templates.md | 4 ++-- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 439af78a..ca7b0429 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Python packages with our recommended tooling set up and ready to go. ## Using our Python package 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. +We also have a longer [tutorial](docs/pages/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: diff --git a/docs/index.md b/docs/index.md index 8a372594..57abef04 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,6 +33,7 @@ other packages. If you just want to get started with our recommendations, we have [our own Python package template](https://github.com/UCL-ARC/python-tooling#using-this-template) that lives in the same repository as these pages. +A [tutorial]({% link pages/tutorial.md %}) explaining how to use the template is also available. Otherwise, each page on this site highlights recommended packages or services for each area. These should not be taken as set in stone for every project, but diff --git a/docs/pages/templates.md b/docs/pages/templates.md index 79e02bb3..01c5685b 100644 --- a/docs/pages/templates.md +++ b/docs/pages/templates.md @@ -1,7 +1,7 @@ --- title: Templates layout: default -nav_order: 2 +nav_order: 3 --- ## Package templates @@ -12,7 +12,7 @@ The [UCL-ARC/python-tooling](https://github.com/UCL-ARC/python-tooling) repository contains our recommended package template for new ARC projects. It pre-configures the recommended tools listed in the other pages of this site. If you are working on a new project, our template should be a good starting point! -We have a [tutorial](https://github.com/UCL-ARC/python-tooling/blob/main/tutorial.md) +We have a [tutorial]({% link pages/tutorial.md %}) available with detailed instructions for creating a package using the template and how to use the newly created package with some of the tools included. From 128b0c1a8ef863da7fda5a48fbe708e7c0f39ad6 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Mon, 2 Feb 2026 12:56:17 +0000 Subject: [PATCH 5/5] Add version specifier for GFM admonition plugin --- docs/Gemfile | 2 +- docs/Gemfile.lock | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Gemfile b/docs/Gemfile index de24d141..6359388f 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -4,5 +4,5 @@ gem 'jekyll', '~>4' group :jekyll_plugins do gem 'just-the-docs','~>0' - gem 'jekyll-gfm-admonitions' + gem 'jekyll-gfm-admonitions', '~>1.2' end diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index a35a0e86..719b6c3b 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -172,7 +172,7 @@ PLATFORMS DEPENDENCIES jekyll (~> 4) - jekyll-gfm-admonitions + jekyll-gfm-admonitions (~> 1.2) just-the-docs (~> 0) BUNDLED WITH