Update to Jupyter Book 0.15.1

book/course/conda.md

@@ -4,6 +4,7 @@ Content from this lesson has been inspired and adapted from a number of sources
 - [Conda documentation](https://docs.conda.io/en/latest/)
 - [Carpentries Incubator: Introduction to Conda for data scientists](https://carpentries-incubator.github.io/introduction-to-conda-for-data-scientists/)
 
+(introduction)=
 ## Introduction
 
 Conda is an open source package management and environment management system that runs on multiple operating systems (Windows, Linux, macOS). Its features include:
@@ -38,6 +39,7 @@ Conda is widely used across scientific computing and data science based domains
 - The cross platform nature of Conda allows for users to more easily share the environments. This helps researchers share their computational environment along side their data and analysis, helping improve the reproducibility of their research
 - Conda also provides access to widely used machine learning and data science libraries such as TensorFlow, SciPy, NumPy that are available as pre-configured, hardware specific packages (such as GPU-enabled TensorFlow) allowing for code to be as performant as possible
 
+(installing-conda)=
 ## Installing Conda
 
 ### On ARC
@@ -77,6 +79,7 @@ This contains a starting installation of Python and the dependencies of the Cond
 Therefore, it's **best practice** to not install packages into the `base` environment and create your own environments into which you install the tools you need.
 ```
 
+(creating-environments)=
 ### Creating environments
 
 You can create an environment with Conda with the subcommand `conda create`. 
@@ -318,6 +321,7 @@ done
 With the above command we create a new environment but don't specify to install Python. 
 However, because we've specified Python packages which depend on Python being installed to run Conda will install the high version of Python suitable for these packages.
 
+(activating-environments)=
 ### Activating environments
 
 To use a Conda environment we need to activate it. 
@@ -332,6 +336,7 @@ $ conda activate data-sci-env
 You use the subcommand `conda activate ENVNAME` for environment activation, where `ENVNAME` is the name of the environment you wish to activate. 
 You can see it has successfully activated when it returns your prompt with the environment name prepended in brackets.
 
+(deactivating-environments)=
 ### Deactivating environments
 
 You can deactivate your current environment with another simple subcommand `conda deactivate`.
@@ -340,6 +345,7 @@ You can deactivate your current environment with another simple subcommand `cond
 (data-sci-env)$ conda deactivate
 ```
 
+(listing-current-environments)=
 ### Listing current environments
 
 If you ever want to see your list of current environments on your machine you can you the subcommand `conda env list`. 
@@ -356,10 +362,11 @@ data-sci-env               /home/home01/arcusers/.conda/envs/data-sci-env
 ```
 ````
 
+(removing-a-conda-environment)=
 ### Removing a Conda environment
 
 It is also possible to delete a Conda environment through the `remove` subcommand. 
-This [command is outlined below](#removing-packages) in relation to removing specific packages but can also be used to delete an entire Conda environment.
+This [command is outlined below](removing-packages) in relation to removing specific packages but can also be used to delete an entire Conda environment.
 
 To remove the `py39-env` we created earlier we use the command:
 
@@ -415,6 +422,7 @@ You cannot undo deletion of an environment to the exact state it was in before d
 However, if you have exported details of your environment it is possible to recreate it.
 ```
 
+(sharing-conda-environments)=
 ### Sharing Conda environments
 
 If you need to share a Conda environment with others or between machines its possible to use Conda to export a file containing a specification of packages installed in that environment.
@@ -523,6 +531,7 @@ With the Conda command line tool searching for and installing packages is can be
 - `conda search`
 - `conda install`
 
+(searching-for-packages)=
 ### Searching for packages
 
 ```bash
@@ -1182,14 +1191,15 @@ python                        3.10.6 ha86cf86_0_cpython  conda-forge
 ```
 ````
 
+(installing-packages)=
 ### Installing packages
 
 Installing packages via Conda is performed using the `install` subcommand with the format `conda install PACKAGE`, where `PACKAGE` is the name of the package you wish to install. 
 
 Earlier we created the `data-sci-env` and installed some useful data science packages. 
 We've discovered we also need the `statsmodels` package for some extra work we want to do so we'll look at using `conda install` to install this package within our existing environment.
 
-To install packages into an existing environment we need to activate it with the [subcommand shown above](#activating-environments).
+To install packages into an existing environment we need to activate it with the [subcommand shown above](activating-environments).
 
 ```bash
 $ conda activate data-sci-env
@@ -1275,6 +1285,7 @@ Executing transaction: done
 This installs any packages that are currently not installed (Conda caches packages locally incase they are required by other packages, this speeds up installs but uses more disk space to maintain this cache).
 
 
+(removing-packages)=
 ### Removing packages
 
 Another crucial aspect of managing an environment involves removing packages. 
@@ -1332,6 +1343,7 @@ As you can see in the above example, removing one package may also lead to the r
 
 With these changes made we can now install a newer version of pandas using `conda install`.
 
+(updating-a-package)=
 ### Updating a package
 
 The above example is slightly artificial as removing a package to install a more recent version is a long-winded way of doing things with Conda.
@@ -1386,19 +1398,19 @@ When requesting to update a package Conda will also update other dependencies of
 
 ```{important}
 
-- [Introduces Conda](#introduction) as a cross-platform package and environment manager 
-- Highlights options for [how to install Conda](#installing-conda)
+- [Introduces Conda](introduction) as a cross-platform package and environment manager 
+- Highlights options for [how to install Conda](installing-conda)
 - Introduces Conda environments for separating specific package dependencies on a project-by-project basis
-  - How to [create an environment using Conda](#creating-environments)
-  - How to use a created Conda environment through [environment activation](#activating-environments)
-  - Leaving an environment through [deactivation](#deactivating-environments)
-  - [Listing available Conda environments](#listing-current-environments)
-  - [Deleting Conda environments](#removing-a-conda-environment)
-  - [Exporting and sharing Conda Environments](#sharing-conda-environments)
+  - How to [create an environment using Conda](creating-environments)
+  - How to use a created Conda environment through [environment activation](activating-environments)
+  - Leaving an environment through [deactivation](deactivating-environments)
+  - [Listing available Conda environments](listing-current-environments)
+  - [Deleting Conda environments](removing-a-conda-environment)
+  - [Exporting and sharing Conda Environments](sharing-conda-environments)
 - Shows how Conda can be used for managing packages
-  - Using Conda to [search Conda repositories for a package](#searching-for-packages)
-  - Using Conda to [install a package](#installing-packages)
-  - Using Conda to [remove a package](#removing-packages)
-  - Using Conda to [update a package](#updating-a-package)
+  - Using Conda to [search Conda repositories for a package](searching-for-packages)
+  - Using Conda to [install a package](installing-packages)
+  - Using Conda to [remove a package](removing-packages)
+  - Using Conda to [update a package](updating-a-package)
 
 ```

book/course/containers.md

@@ -1,5 +1,6 @@
 # Containers
 
+(containers:what)=
 ## What are containers?
 
 Containers are a bit like VMs, but less contained than that.  It probably helps
@@ -26,6 +27,7 @@ unlike a container which can use all of the host system's memory, in the same
 way a normal process can.  This lack of total containment also means you get
 full access to the network and GPUs of the host.
 
+(containers:why)=
 ## Why do I want a container?
 
 One of the problems with running software on different systems is that it can
@@ -36,6 +38,7 @@ use it on quite different systems.  By also publishing the recipe, you make it
 very clear how you created this software environment, making it much easier to
 update this in future.
 
+(containers:docker-hpc)=
 ## Can I use Docker on HPC?
 
 **No.**
@@ -48,6 +51,7 @@ containers, but via a tool that uses an alternative security model, where
 containers run with the permissions of the user who is running them.  That
 makes them perfect for HPC, where we want all your work to run as your user.
 
+(containers:singularity-vs-apptainer)=
 ## Singularity vs Apptainer
 
 First there was Singularity, then there was commercialisation that kept an open
@@ -59,6 +63,7 @@ Singularity, we'll only be looking at Apptainer.
 Singularity provides a `singularity` command instead of `apptainer`, which
 mostly behaves the same.  Apptainer provides both for backwards compatibility.
 
+(containers:example)=
 ## Example of running a container
 
 It's always good to do something simple to start with, to prove to yourself
@@ -96,18 +101,21 @@ It might not look on the face of it that this is very impressive, but we've just
 
 ### What do those steps mean?
 
+(containers:pulling-from-docker)=
 #### Pulling a container image down from Docker Hub
 
 Docker Hub is a repository of containers, also known as a container registry.  Pulling down a container involves
 pulling down the pieces of this container image over to your machine.
 
+(containers:converting-to-sif)=
 #### Converting it into a SIF image
 
 Docker uses a container format that involves a number of layers, that add up
 together to form your final container image.  Singularity uses a different
 format SIF, which is a single file that contains everything you need to run
 your container.
 
+(containers:running-within)=
 #### Running software within a container
 
 When you come to use a container, you can run software inside the container,
@@ -125,6 +133,7 @@ to directories of the host mapped into the container.
 
 ## What else can I do with containers?
 
+(containers:host-storage)=
 ### Access host storage within a container
 
 By default with Apptainer, your home directory and `/tmp` are mapped into the
@@ -143,19 +152,22 @@ is presented within the container as `/scratch`):
 $ apptainer run -B /data:/scratch example.sif
 ```
 
+(containers:run-alternative-command)=
 ### Run an alternative command within a container
 
 ```bash
 $ apptainer exec example.sif cat /etc/issue
 Ubuntu 16.04.3 LTS \n \l
 ```
 
+(containers:shell)=
 ### Have an interactive shell inside the container
 
 ```bash
 $ apptainer shell example.sif
 ```
 
+(containers:gpu)=
 ### Use GPUs within a container
 
 Singularity has a lovely way of pulling drivers and libraries for the GPU from
@@ -171,6 +183,7 @@ All available Nvidia GPUs are then visible to the container, along with the
 necessary drivers to use them.  If you need a CUDA SDK or similar, that would
 need to be included within the container.
 
+
 ## Building a container
 
 Now, what if an existing Docker container doesn't exist, and I want to build
@@ -188,6 +201,7 @@ already available.
 
 This is also now available on ARC4.
 
+(containers:recipe)=
 ### Creating a recipe
 
 A recipe lists all the steps needed to make a container, and also what happens
@@ -212,6 +226,7 @@ From: ubuntu:16.04
 
 This container starts with a Docker container (Ubuntu 16.04), and installs a few necessary packages.  Then it defines what happens when we run it: `fortune | cowsay | lolcat`.
 
+(containers:convert-from-dockerfile)=
 ### Converting a Dockerfile to a Singularity recipe
 
 There's a tool written in Python that allows you to convert from a Dockerfile into a Singularity format file.  Whilst not perfect, this often allows for simple creations of images, where no prebuilt Docker image exists:
@@ -232,12 +247,14 @@ $ spython recipe Dockerfile lolcow.def
 
 Then you could proceed to build it into a SIF file as show below.
 
+(containers:generate-sif)=
 ### Generate a SIF image from a recipe
 
 ```bash
 $ apptainer build lolcow.sif lolcow.def
 ```
 
+(containers:test)=
 ### Test the image we've created
 
 ```
@@ -253,6 +270,7 @@ $ apptainer run lolcow.sif
                 ||     ||
 ```
 
+(containers:submit-job)=
 ## Submitting jobs with containers
 
 There's no great difference with submitting jobs to use containers than there
@@ -281,6 +299,7 @@ apptainer exec lolcow_latest.sif fortune
 There's more content we'd like to include than we've really got time for, but
 some bonus content is available here.
 
+(containers:sandbox)=
 ````{admonition} Sandboxes
 :class: dropdown
 
@@ -306,25 +325,25 @@ You can now experiment inside this sandbox to work out what you need for your re
 ## Summary
 
 ```{important}
-- [What are containers](#what-are-containers)?
-- [Why do I want a container](#why-do-i-want-a-container)?
-- [Can I use Docker on HPC](#can-i-use-docker-on-hpc)?
-- [Singularity vs Apptainer](#singularity-vs-apptainer)
-- [Example of running a container](#example-of-running-a-container) and a look into the steps involved:
-    - [Pulling a container image down from Docker Hub](#pulling-a-container-down-from-docker-hub)
-    - [Converting it into a SIF image](#converting-it-into-a-sif-image)
-    - [Running software within a container](#running-software-within-a-container)
+- [What are containers](containers:what)?
+- [Why do I want a container](containers:why)?
+- [Can I use Docker on HPC](containers:docker-hpc)?
+- [Singularity vs Apptainer](containers:singularity-vs-apptainer)
+- [Example of running a container](containers:example) and a look into the steps involved:
+    - [Pulling a container image down from Docker Hub](containers:pulling-from-docker)
+    - [Converting it into a SIF image](containers:converting-to-sif)
+    - [Running software within a container](containers:running-within)
 - What else can I do with containers?
-  - [Access host storage within a container](#access-host-storage-within-a-container)
-  - [Run an alternative command within a container](#run-an-alternative-command-within-a-container)
-  - [Have an interactive shell inside the container](#have-an-interactive-shell-inside-the-container)
-  - [Use GPUs within a container](#use-gpus-within-a-container)
+  - [Access host storage within a container](containers:host-storage)
+  - [Run an alternative command within a container](containers:run-alternative-command)
+  - [Have an interactive shell inside the container](containers:shell)
+  - [Use GPUs within a container](containers:gpu)
 - Building a container
-  - [Creating a recipe](#creating-a-recipe)
-  - [Converting a Dockerfile to a Singularity recipe](#converting-a-dockerfile-to-a-singularity-recipe)
-  - [Generate a SIF image from a recipe](#generate-a-sif-image-from-a-recipe)
-  - [Test the image we've created](#test-the-image-we-ve-created)
-- [Submitting jobs with containers](#submitting-jobs-with-containers)
+  - [Creating a recipe](containers:recipe)
+  - [Converting a Dockerfile to a Singularity recipe](containers:convert-from-dockerfile)
+  - [Generate a SIF image from a recipe](containers:generate-sif)
+  - [Test the image we've created](containers:test)
+- [Submitting jobs with containers](containers:submit-job)
 - Bonus section
-  - [Sandboxes](#sandboxes)
+  - [Sandboxes](containers:sandbox)
 ```

book/course/spack/advanced.md

@@ -5,6 +5,7 @@ dependencies to use.  You're able to adjust some of this via variants within an
 individual package, but also you can tweak the dependency decisions, to use
 different packages if you know better than the defaults.
 
+(advanced:spack:variants)=
 ## Variants
 
 Variants are where the package has options how to build it.  Let's pick on

book/course/spack/modules.md

@@ -21,7 +21,7 @@ One option is to simplify this a great deal, hiding a lot of that information,
 which might be appealing if you know that information is not important to you.
 So if you're using one compiler, you don't really care about the compiler used,
 you don't need the hash at the end if you're only dealing with a single variant
-(covered [later](advanced.html#variants)), and you'd probably like the modules
+(covered [later](advanced:spack:variants)), and you'd probably like the modules
 names more in line with how they have traditionally been named, with the
 version separate from the package name.
 

environment.yml

@@ -5,4 +5,4 @@ channels:
 dependencies:
   - python=3.9
   - jinja2=3.0.3
-  - jupyter-book==0.13.1
+  - jupyter-book==0.15.1