diff --git a/README.md b/README.md index 11cf66e6..ca8cecd3 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. 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). diff --git a/docs/Gemfile b/docs/Gemfile index 5b4c4eaa..6359388f 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', '~>1.2' end diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index b84964bd..719b6c3b 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 (~> 1.2) 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 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. diff --git a/tutorial.md b/docs/pages/tutorial.md similarity index 98% rename from tutorial.md rename to docs/pages/tutorial.md index b01ce2ca..f9a51cc4 100644 --- a/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