Move tutorial to Jekyll website (#613)

Resolves #577 

Moves template tutorial under website `docs/pages` directory and updates
internal links to point to new location.

To get GFM admonitions to render on Jekyll site also adds
[jekyll-gdm-admonitions](https://github.com/Helveg/jekyll-gfm-admonitions)
plugin as a new dependency on site config and Gemfile. As an alternative
we could use the [built-in support for callouts / admonitions in the
Just the Docs
theme](https://just-the-docs.com/docs/ui-components/callouts/). This
would then no longer render on GitHub though.

I have currently updated the link on main README to still be version on
GitHub rather than rendered website - not sure if we want to change this
or not.

The additional attributes on `<details>` / `<summary>` tags are taken
from [this blog
post](https://rolandtanglao.com/2024/11/02/p1-collapsible-sections-details-html-tag-test/).

Author: matt-graham

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.
 Slides from presentations we have given on the project are available in the
 [`python-tooling-presentations` repository](https://github.com/ucl-arc/python-tooling-presentations).
 

docs/Gemfile

@@ -4,4 +4,5 @@ gem 'jekyll', '~>4'
 
 group :jekyll_plugins do
     gem 'just-the-docs','~>0'
+    gem 'jekyll-gfm-admonitions', '~>1.2'
 end

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 (~> 1.2)
   just-the-docs (~> 0)
 
 BUNDLED WITH

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

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

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.
 

tutorial.md docs/pages/tutorial.mdtutorial.md renamed to 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
 
-<details><summary>Click to expand… </summary> <!-- markdownlint-disable-line MD033 -->
+<details markdown="1"><summary markdown="span">Click to expand… </summary> <!-- markdownlint-disable-line MD033 -->
 
 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.
 
-<details><summary>Using venv as an alternative to uv </summary> <!-- markdownlint-disable-line MD033 -->
+<details markdown="1"><summary markdown="span">Using venv as an alternative to uv </summary> <!-- markdownlint-disable-line MD033 -->
 
 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