Reorganise tutorials and add inline solutions

This commit works in conjunction with the updates in
seL4/sel4-tutorials#106.

Aim: To arrange the tutorial material such that it is clear and easy to
follow.

Solution: Inspired by the Rust book https://doc.rust-lang.org/book/,
users can see the chapters in the index on the left, and go straight to
the sections that they need.

Specifically, updated tutorials with:

- a streamlined guide to completing the tutorials
- a streamlined "setting up your machine" page
- a how-to page with solutions to tutorial questions
-  more organised landing page

Changes:

- Rename “Getting Started” block to “Resources” since this section of
  the docsite contains much more than a “Setting up your machine” page.
- Change “Get Help” sections to “Contact”
- In Make tutorials, filter out index.md; get-the-tutorials.md;
  how-to.md pathways.md; setting-up.md, which are docsite pages, and not
  in the tutorials repo
- change most tutorial .md files in /Tutorials to layout: tutorial
- Rearrange order of tutorials
- Add relative links
- Add html + css for displaying tutorials sidebar
- Add css for displaying solutions
- Add layout for tutorials overview page and tutorial pages
- Add code to toggle solutions boxes; specifically to open solutions
  boxes when coming from how-to page
- Rewrite landing page to reorder tutorials and include the  how-to
  page, seL4 manual, API reference, Microkit and Rust

Specific files:

Tutorials/get-the-tutorials.md:
- Add steps and code for running the tutorials

Tutorials/how-to.md:
- Add a quick solutions guide, which provides links to tutorial
  solutions as quick references for seL4 calls and methods

Tutorials/index.md
- Add an overview on the tutorials section of the docsite
- Remove excessive detail about pathways through the tutorials. A new
  Tutorials/pathways.md page has been created instead, which follows on
  from index.md

Tutorials/pathways.md
- Add recommended pathways through tutorials, depending on development
  goals

Tutorials/setting-up.md
- Add simplified setting-up page to ease the user into running seL4 and
  the tutorials

_includes/tutorial.md
- Remove old capture paths

Signed-off-by: Birgit Brecknell <[email protected]>
Signed-off-by: Gerwin Klein <[email protected]>

Hardware/Beaglebone.md

@@ -27,7 +27,7 @@ a community-supported port.
 
 ### Requirements
 We suggest using the `arm-linux-gnueabi-` cross-compilers. Use
-[the instructions on getting a toolchain](/GettingStarted#getting-cross-compilers).
+[the instructions on getting a toolchain](/Resources#getting-cross-compilers).
 
 ### Building
 

Hardware/HiKey/index.md

@@ -23,7 +23,7 @@ SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 - One HiKey Board. See
         [Hikey 96Board](http://www.96boards.org/products/ce/hikey/)
 - Fully working development environment. See
-        [Getting started](/GettingStarted)
+        [Resources](/Resources)
 
 ### Getting Started
  The Hikey board is based around the
@@ -87,12 +87,12 @@ gedit LinaroPkg/platforms.config
 BUILDFLAGS=-DSERIAL_BASE=0xF8015000
 ATF_BUILDFLAGS=CONSOLE_BASE=PL011_UART0_BASE CRASH_CONSOLE_BASE=PL011_UART0_BASE
 ```
-## 5. Patching the UEFI for the Hikey 
+## 5. Patching the UEFI for the Hikey
 Obtain the patch from [edk2.patch](edk2.patch) and follow the below steps.
 
 ```bash
-cd linaro-edk2 
-patch -p1 < ~/Downloads/edk2.patch 
+cd linaro-edk2
+patch -p1 < ~/Downloads/edk2.patch
 # Then return to the main directory hikey-flash
 ```
 
@@ -206,8 +206,8 @@ sudo minicom -s
   7.  Three terminals are then required for the following commands
 
 ```bash
-# In the first terminal 
-ls 
+# In the first terminal
+ls
 # Note the next ttyUSBY that is observed, in addition to the current ttyUSBX
 
 # In the third terminal

Hardware/VMware/index.md

@@ -14,7 +14,7 @@ and for a Linux host machine. May work on Mac host machine, won't work
 for Windows host (although general idea should be similar).
 
 This guide assumes that your project is all set up and configured to
-build for x86. Read [Getting started](/GettingStarted) otherwise.
+build for x86. Read [Resources](/Resources) otherwise.
 
 ## Setting up a VM
 
@@ -55,7 +55,7 @@ There are three options for the serial port
 set up). You'll want to apt-get install socat and then run something
 like:
 ```bash
-#!/bin/bash 
+#!/bin/bash
 while true; do
     socat -d -d UNIX-CONNECT:/tmp/vsock,forever PTY:link=/dev/tty99
 done

Hardware/jetsontk1.md

@@ -20,10 +20,10 @@ SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 
 The [Jetson TK1](http://www.nvidia.com/object/jetson-tk1-embedded-dev-kit.html) is a affordable embedded system developed by NVIDIA. It runs
 seL4. We will explain how to run seL4 on the Tegra.
- 
+
 ### Pre-Requisites
 * One Tegra Board. See [Jetson TK1](http://www.nvidia.com/object/jetson-tk1-embedded-dev-kit.html)
-* The development environment fully working.  See [Getting started](/GettingStarted)
+* The development environment fully working.  See [Resources](/Resources)
 
 ## Getting Started
  To get started, check out the
@@ -94,7 +94,7 @@ to boot in nonsecure (HYP)
 mode. This also enables kvm if you boot Linux.
 
 To go back to secure mode booting do
-``` 
+```
 setenv bootm_boot_mode sec
 saveenv
 ```

Makefile

@@ -51,7 +51,10 @@ _repos/tutes:
 _repos/tutes/%.md: _repos/sel4proj/sel4-tutorials/tutorials/% _repos/tutes
 	PYTHONPATH=_repos/sel4/capdl/python-capdl-tool _repos/sel4proj/sel4-tutorials/template.py --docsite --out-dir _repos/tutes --tut-file $</$(@F)
 
-TUTORIALS:= $(filter-out index.md,$(notdir $(wildcard Tutorials/*.md)))
+# Make tutorials
+# Filter out index.md; get-the-tutorials.md; how-to.md pathways.md; setting-up.md
+# which are docsite pages, and not in the tutorials repo
+TUTORIALS:= $(filter-out index.md get-the-tutorials.md how-to.md pathways.md setting-up.md,$(notdir $(wildcard Tutorials/*.md)))
 tutorials: ${TUTORIALS:%=_repos/tutes/%}
 
 _generate_api_pages: $(REPOSITORIES)

GettingStarted.md → Resources.md

@@ -5,9 +5,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 
-# Getting Started
+# Resources
 
-This page is a quick start for working with seL4 and its ecosystem.
+This page provides an overview of working with seL4 and its ecosystem.
 
 ## Background and terminology
 
@@ -168,7 +168,12 @@ You can find a long list of seL4 publications here:
 - [seL4 is free: What does this mean for you? (2015)](https://www.youtube.com/watch?v=lRndE7rSXiI).
 - [From L3 to seL4: What have we learned in 20 years of L4 microkernels? (2014)](https://www.youtube.com/watch?v=RdoaFc5-1Rk).
 
-## Get Help
+## Contact
+
+### Forums
+
+- [Discourse forum](https://sel4.discourse.group/)
+- [Mattermost channel](https://mattermost.trustworthy.systems/sel4-external/)
 
 ### Mailing lists
 

SuggestedProjects.md

@@ -6,7 +6,7 @@ SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 # Suggested Projects
 
 
-After trying the existing projects (especially those listed on [Getting started](GettingStarted))
+After trying the existing projects (e.g. the [Tutorials](Tutorials))
 a good way to learn the intricacies of programming on
 top of seL4 is to do the exercises in the
 [UNSW Advanced

Tutorials/camkes-vm-crossvm.md

@@ -1,11 +1,11 @@
 ---
 toc: true
-title: Camkes Cross-VM communication
+title: Camkes cross-VM connectors
 tutorial: camkes-vm-crossvm
+description: walkthrough of adding communication between Linux guests in separate VMs
 tutorial-order: vm-2
-description: walkthrough of adding communication between Linux guests in separate VMs.
+layout: tutorial
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
-{% include tutorial.md %}
-
+{% include tutorial.md %}

Tutorials/camkes-vm-linux.md

@@ -3,9 +3,9 @@ toc: true
 title: Camkes VM Linux
 tutorial: camkes-vm-linux
 tutorial-order: vm-1
-description: using Linux as a guest in the Camkes VM.
+layout: tutorial
+description: using Linux as a guest in the Camkes VM
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
-

Tutorials/capabilities.md

@@ -2,9 +2,10 @@
 toc: true
 title: Capabilities
 tutorial: capabilities
-tutorial-order: mechanisms-1
-description: an introduction to capabilities in the seL4 kernel API.
+layout: tutorial
+description: an introduction to capabilities in the seL4 kernel API
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
+
 {% include tutorial.md %}

Tutorials/fault-handlers.md

@@ -2,8 +2,8 @@
 toc: true
 title: Faults
 tutorial: fault-handlers
-tutorial-order: mechanisms-8
-description: fault (e.g virtual memory fault) handling and fault endpoints.
+layout: tutorial
+description: fault (e.g virtual memory fault) handling and fault endpoints
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---

Tutorials/get-the-tutorials.md

@@ -0,0 +1,33 @@
+---
+toc: true
+title: Getting the tutorials
+layout: tutorial
+description: steps and code for getting tutorials
+SPDX-License-Identifier: CC-BY-SA-4.0
+SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC.
+---
+
+# Getting the tutorials
+## Python Dependencies
+The CAmkES python dependencies are required to build the [tutorials](ReworkedTutorials). To install you can run:
+```
+pip3 install --user camkes-deps
+```
+*Hint:* This step only needs to be done once, i.e. before doing your first tutorial.
+
+## Get the code
+All code for the tutorials is described in the <a href="https://github.com/seL4/sel4-tutorials-manifest">sel4-tutorials-manifest</a>. Get the code with:
+```
+mkdir sel4-tutorials-manifest
+cd sel4-tutorials-manifest
+repo init -u https://github.com/seL4/sel4-tutorials-manifest
+repo sync
+```
+
+`repo sync` may take a few moments to run
+
+*Hint:* The **Get the code** step only needs to be done once, i.e. before doing your first tutorial.
+
+<p>
+    Next: <a href="hello-world">Hello world</a>
+</p>

Tutorials/hello-camkes-0.md

@@ -1,11 +1,10 @@
 ---
 toc: true
-title: Camkes
+title: Hello CAmkES
 tutorial: hello-camkes-0
-tutorial-order: camkes-0
-description: an introduction to Camkes concepts.
+layout: tutorial
+description: an introduction to CAmkES concepts
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
-

Tutorials/hello-camkes-1.md

@@ -1,11 +1,10 @@
 ---
 toc: true
-title: Camkes 1
+title: Introduction to CAmkES
 tutorial: hello-camkes-1
-tutorial-order: camkes-1
-description: an introduction to Camkes concepts.
+layout: tutorial
+description: an introduction to CAmkES concepts
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
-

Tutorials/hello-camkes-2.md

@@ -1,11 +1,10 @@
 ---
 toc: true
-title: Camkes 2
+title: Events in CAmkES
 tutorial: hello-camkes-2
-tutorial-order: camkes-2
-description: an introduction to Camkes concepts.
+layout: tutorial
+description: an introduction to CAmkES concepts
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
-

Tutorials/hello-camkes-timer.md

@@ -1,11 +1,10 @@
 ---
 toc: true
-title: Camkes 3
+title: CAmkES timer tutorial
 tutorial: hello-camkes-timer
-tutorial-order: camkes-3
-description: introduce Camkes hardware components.
+layout: tutorial
+description: introduce CAmkES hardware components
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
-

Tutorials/hello-world.md

@@ -2,9 +2,10 @@
 toc: true
 title: Hello, World!
 tutorial: hello-world
-tutorial-order: 0-hello
-description: an introduction to seL4 projects and tutorials.
+layout: tutorial
+description: an introduction to seL4 projects and tutorials
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
+
 {% include tutorial.md %}