DOCSITE: Reorganise tutorials and add inline solutions #231

bbrcknl · 2024-03-18T00:25:49Z

Aim: 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/, the user 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

To-dos:

The new tutorial md files are not those from the tutorials repo. The md files in the tutorials repo need to be updated to match the tutorials in this PR, which include solutions and corrections. The new tutorial md files then need to be rewritten as includes to read in the md files from the tutorials repo.
Sections on the docsite, other than the tutorials, need to be streamlined

Indanz · 2024-03-19T13:55:33Z

In the preview you gave it looked great, good work!

To-dos:

* The new tutorial md files _are not_ those from the tutorials repo. The md files in the tutorials repo need to be updated to match the tutorials in this PR, which include solutions and corrections. The new tutorial md files then need to be rewritten as includes to read in the md files from the tutorials repo.

Because this hasn't been done yet, I can't see what your changes to the tutorial files themselves are, making reviewing it difficult. I can do a manual diffs between _repos/sel4proj/sel4-tutorials/tutorials/* and Tutorials/*, but that is cumbersome.

I used the following diff to build and preview the site locally:

diff --git a/Gemfile b/Gemfile
index 9e06a50e54..363f7f04eb 100644
--- a/Gemfile
+++ b/Gemfile
@@ -27,6 +27,7 @@ group :jekyll_plugins do
   gem 'jekyll-toc'
   gem 'jekyll-redirect-from'
   gem 'jekyll-remote-theme'
+  gem "jekyll-sass-converter", "~> 2.0" # TODO: Prevent 3.0 untill sass warnings are fixed
 end
 
 # Windows does not include zoneinfo files, so bundle the tzinfo-data gem
diff --git a/_config.yml b/_config.yml
index 65f4b8b9a2..b56c93e493 100644
--- a/_config.yml
+++ b/_config.yml
@@ -129,3 +129,4 @@ exclude:
   - assets/css/highlighting/demos
   - assets/css/highlighting/tools
   - assets/css/highlighting/index.html
+  - Tutorials-old

On the http://0.0.0.0:4000/Tutorials/ page, the two blocks on the right don't seem right and point to the wrong url? Maybe they shouldn't always be generated, but only on some pages where it makes sense.

The "Tutorials about seL4" page has some broken urls (e.g. "About seL4"), mostly missing the new subdirectories you added for the tutorials, but other pages also have broken links.

The "Quick solution" need a bit more margin below them and it would help if the mouse pointer would change when hovering above them, both can be fixed with a small css change. Also, when adding a new CSS rule, remove all existing styles from the HTML.

It would be nice if, when clicking on a link in "How to: A quick solutions guide", the Quick solution would be expanded automatically. We can add this in the future, but it will require some Javascript (It needs to check a GET or POST variable and set open to true for all details elements).

All in all my first impression is that the new structure is a lot better and makes more sense compared to what we have now. I'll give more detailed feedback later, maybe when the changes are moved to the tutorials repo.

bbrcknl · 2024-03-22T02:04:34Z

@Indanz

In the preview you gave it looked great, good work!

Thanks!

To-dos:
* The new tutorial md files _are not_ those from the tutorials repo. The md files in the tutorials repo need to be updated to match the tutorials in this PR, which include solutions and corrections. The new tutorial md files then need to be rewritten as includes to read in the md files from the tutorials repo.
Because this hasn't been done yet, I can't see what your changes to the tutorial files themselves are, making reviewing it difficult. I can do a manual diffs between _repos/sel4proj/sel4-tutorials/tutorials/* and Tutorials/*, but that is cumbersome.

I suggest waiting to review the tutorials until I've made the changes in the tutorials repo, then you'll be able to see line-by-line diffs.
I will start that early next week and keep you posted. It will take ~2 weeks.

On the http://0.0.0.0:4000/Tutorials/ page, the two blocks on the right don't seem right and point to the wrong url? Maybe they shouldn't always be generated, but only on some pages where it makes sense.

I have added two new layouts to the Tutorial pages to remove the blocks that don't make sense.
_layouts/overview.html
_layouts/tutorial.html

The "Tutorials about seL4" page has some broken urls (e.g. "About seL4"), mostly missing the new subdirectories you added for the tutorials, but other pages also have broken links.

The urls have been fixed.

The "Quick solution" need a bit more margin below them and it would help if the mouse pointer would change when hovering above them, both can be fixed with a small css change. Also, when adding a new CSS rule, remove all existing styles from the HTML.

TBD: Integrate CSS with markdown for quick solutions

It would be nice if, when clicking on a link in "How to: A quick solutions guide", the Quick solution would be expanded automatically. We can add this in the future, but it will require some Javascript (It needs to check a GET or POST variable and set open to true for all details elements).

TBD: Integrate js with markdown to expand solutions automatically

All in all my first impression is that the new structure is a lot better and makes more sense compared to what we have now. I'll give more detailed feedback later, maybe when the changes are moved to the tutorials repo.

bbrcknl · 2024-05-27T07:46:14Z

The tutorials have now been updated to fit into the new tutorial structure as per this PR (#231).

The new tutorials: seL4/sel4-tutorials#106

A note on using the rewritten docsite (#231):
While the docsite in this PR has the new tutorial layout, the Makefile clones the old tutorials from https://github.com/seL4/sel4-tutorials.
You’ll need to integrate the updated tutorials (from this PR) in the Makefile from #231

Previous TODOs:

The "Quick solution" need a bit more margin below them and it would help if the mouse pointer would change when hovering above them, both can be fixed with a small css change. Also, when adding a new CSS rule, remove all existing styles from the HTML.

I’ve added a margin below the “Quick solutions”
I haven’t updated the mouse to hover over the solution.
@Indanz What do you mean by “when adding a new CSS rule, remove all existing styles from the HTML”?

It would be nice if, when clicking on a link in "How to: A quick solutions guide", the Quick solution would be expanded automatically. We can add this in the future, but it will require some Javascript (It needs to check a GET or POST variable and set open to true for all details elements).

I’ve integrated js with markdown to expand solutions automatically, but only when coming from the How-to page. Is this sufficient, or do we also need an “Expand all solutions” button on each tutorial page?

lsf37 · 2024-07-08T03:01:34Z

(rebased to more easily see the new commits)

.ruby-version

Gemfile.lock

lsf37 · 2024-07-08T05:16:32Z

Ok, I've managed to get it working, and before I start reviewing all the small details, it's probably better to start high level:

The new inline solutions and the resulting how-to guide are really cool!
I still need to go through all the parts, but I also like the new flow. There are some things to update in the details, though:
- the "about seL4 page" in the beginning doesn't really fit. It's too long-winded and not aimed at tutorial level. We should probably start with the overview page instead (also not the Microkit).
- the Microkit page calls the Microkit "an operating system framework". I don't think that name is right, and I'm not sure the page as such helps much. We might want to replace links to this page directly with links to the Microkit tutorial (not sure if that always works).
- the overview page says "a basic understanding of seL4, e.g. by having done the Microkit tutorial." -- the Microkit tutorial is mostly hiding seL4 and not really providing much understanding on what seL4 is or does. The seL4 white paper might be a better resource for this one. I'm fine with pointing people at the Microkit tutorial as a potential very first step, but it needs to be clear that you won't really learn much about seL4 that way -- you'll learn how to build systems with a static architecture on top of seL4 there, which might be all that people want, but it's slightly different to the rest.
- the overview page doesn't really give an overview of the tutorials. It should. It should explain when you want to do/use Microkit, seL4 directly and/or CAmkES. Also what MCS is, what the dynamic libraries are about, and that there is Rust support.
- the prerequisites look a bit scary -- it's good that they are there, but it looks like I first have to read all of these before I can run "Hello world", which is not the case. You do need a background in OS for many of the other things, so I don't think we should remove the section, but we might for instance kick out the two wikipedia links that aren't really much good for learning anything (and if you do read the OS book, you'll get enough background for these).
the new front page doesn't really work for me -- possibly because I have the browser on half screen size by default (which is similar to tablet size), and having 3 columns there looks not so great. The old 2 column design is about as much as can fit with that column size. How about leaving the main design intact for now, just changing the links under "Tutorials" there? (and making "Tutorials" itself not a link). Could still be tutorials, howtos, and manual. I would possibly add API Reference if there is space
a lot of the general menu links in unrelated parts of the site are now rendered as going off-site (probably just some small tweak somewhere, but needs to be fixed)
I'd replace the links to forum, etc in the Resources section of the nav section on the left with a single link to a contact page
Not sure the rename from "Getting Started" into "Working with seL4" is a success. The problem is more the content of that page, not so much what it is called ;-). In any case, "Working with seL4" is too long -- it line-breaks on narrower screens and looks bad when it does. Whatever name we pick should be narrower than the min size of the rest of the card on the front page. It'd be great to have an actual good Getting Started page, but that might lead a bit far astray from the purpose of this PR. I'd be fine with removing the links to that page from the top-level navigation and calling the heading on the front page "Resources" or something generic like that (without link to this specific page).

Makefile

Tutorials/CAmkES/camkes-vm-linux.md

lsf37 · 2024-07-08T05:28:37Z

Tutorials/index.md

-## How to use the tutorials
-
-Depending on your goals and what you want to do with seL4, we suggest
-different paths to follow through the tutorial material.  Choose the
-most relevant category below and follow the tutorials in the suggested
-order.


I do think that section and set of paths was useful. We should not remove that completely, just recommend a default path (which the site navigation basically suggests now). There is a lot of useful content overview in here that we could use in the overview page.

Much of this page has been put into the new Overview and Pathways pages, which describe the tutorials and alternate pathways respectively.

lsf37 · 2024-07-08T05:30:13Z

Tutorials/index.md

+<h2>Categories</h2>
+The tutorials are split into a number of broad categories:
+
+- [About seL4](GettingStarted/about-seL4) and [Getting started with the Microkit tutorial](GettingStarted/microkit) introduce seL4 concepts.
+- The [seL4 Kernel tutorials](seL4Kernel/overview.md) are a deep dive into seL4 concepts.
+- [MCS](MCS/mcs) introduces seL4 MCS extensions.
+- [Dynamic Libraries](DynamicLibraries/dynamic-1) covers the libraries that have been developed for rapidly prototyping systems on seL4.
+- [CAmkES](CAmkES/hello-camkes-0) is a platform for building componentised systems for embedded platforms.
+- [Microkit](https://trustworthy.systems/projects/microkit/tutorial/)is an operating system framework on top of seL4 provides a small set of simple abstractions that ease the design and implementation of statically structured systems on seL4. (Links to the same tutorial as in the [Getting Started](GettingStarted/microkit) section.)
+- [Rust](https://github.com/seL4/rust-sel4) provide crates for supporting the use of Rust in seL4 userspace.


I did not come across this content when I was navigating the new site -- which page does it get rendered to?

This page was rendered when the user clicked on "Tutorials." I've now redirected "Tutorials" to overview, and used much of the above content in the overview page.

Tutorials/seL4Kernel/get-the-tutorials.md

Tutorials/seL4Kernel/setting-up.md

lsf37 · 2024-07-08T05:38:49Z

Tutorials/seL4Kernel/setting-up.md

+## Docker
+To compile and use seL4, it is recommended that you use Docker to isolate the dependencies from your machine.


If we are recommending docker, we don't really need the rest of the page apart from repo (although I don't know if the virtual machine tutorials actually work under docker). We either should remove the docker section or add some text that makes clear that docker and the rest are two alternatives, and that you need only one of them.

I actually removed everything but the repo and docker sections, because there is a whole other page on dependencies https://docs.sel4.systems/projects/buildsystem/host-dependencies.html, should someone need them.

I couldn't get of the virtual machine tutorials working on my silicon mac (but I don't think it's related to Docker at all).

Adding issues here for completeness:

"CAmkES VM: Adding a Linux Guest" uses KVM and I would have needed an alternative for mac.

"CAmkES VM: Cross VM Connectors" breaks using ninja.

sh.ErrorReturnCode_1: RAN: /usr/bin/cmake -G Ninja -DTUT_BOARD=pc -DTUT_ARCH=x86_64 -DFORCE_IOMMU=ON -DTUTORIAL_DIR=camkes-vm-crossvmke7jqji2 -C ../projec STDOUT: STDERR:

Should I add a note to these tutorials saying the instructions are for Linux only?

Yes, that would be good. We've already had some questions from people who were trying to use other platforms.

Tutorials/seL4Kernel/setting-up.md

lsf37 · 2024-07-08T05:41:22Z

Tutorials/seL4Kernel/setting-up.md

+## Getting a build environment
+To get a running build environment for seL4 and Camkes, run:
+
+```bash
+git clone https://github.com/seL4/seL4-CAmkES-L4v-dockerfiles.git
+cd seL4-CAmkES-L4v-dockerfiles
+make user


These are now docker instructions again. They should be in the docker section.

Tutorials/seL4Kernel/setting-up.md

lsf37 · 2024-07-09T22:50:43Z

(have rebased and removed the edits to Gemfile.lock + .ruby-version)

bbrcknl · 2024-07-14T23:02:44Z

The new inline solutions and the resulting how-to guide are really cool!

Thanks!

I still need to go through all the parts, but I also like the new flow. There are some things to update in the details, though:

the "about seL4 page" in the beginning doesn't really fit. It's too long-winded and not aimed at tutorial level. We should probably start with the overview page instead (also not the Microkit).

I've removed the "about seL4" and started with "overview" instead

the Microkit page calls the Microkit "an operating system framework". I don't think that name is right, and I'm not sure the page as such helps much. We might want to replace links to this page directly with links to the Microkit tutorial (not sure if that always works).

I got the wording from https://docs.sel4.systems/projects/microkit/

In any case, I've removed the GettingStarted page that was dedicated to the Microkit tutorial

the overview page says "a basic understanding of seL4, e.g. by having done the Microkit tutorial." -- the Microkit tutorial is mostly hiding seL4 and not really providing much understanding on what seL4 is or does. The seL4 white paper might be a better resource for this one. I'm fine with pointing people at the Microkit tutorial as a potential very first step, but it needs to be clear that you won't really learn much about seL4 that way -- you'll learn how to build systems with a static architecture on top of seL4 there, which might be all that people want, but it's slightly different to the rest.

In the new "pathways" page (which lists alternative pathways through the tutorials), I have suggested that new developers start with Microkit as a very first step, with the caveat that Microkit hides seL4 mechanisms. Can take it out if you think it's misleading.

the overview page doesn't really give an overview of the tutorials. It should. It should explain when you want to do/use Microkit, seL4 directly and/or CAmkES. Also what MCS is, what the dynamic libraries are about, and that there is Rust support.

Details have now been added.

the prerequisites look a bit scary -- it's good that they are there, but it looks like I first have to read all of these before I can run "Hello world", which is not the case. You do need a background in OS for many of the other things, so I don't think we should remove the section, but we might for instance kick out the two wikipedia links that aren't really much good for learning anything (and if you do read the OS book, you'll get enough background for these).

I removed the wikipedia links and changed "prerequisites" to (the hopefully less scary) "recommended reading"

the new front page doesn't really work for me -- possibly because I have the browser on half screen size by default (which is similar to tablet size), and having 3 columns there looks not so great. The old 2 column design is about as much as can fit with that column size. How about leaving the main design intact for now, just changing the links under "Tutorials" there? (and making "Tutorials" itself not a link). Could still be tutorials, howtos, and manual. I would possibly add API Reference if there is space

Went back to the two-column format and put howtos and manual under "Tutorials"

a lot of the general menu links in unrelated parts of the site are now rendered as going off-site (probably just some small tweak somewhere, but needs to be fixed)

Can you pls give an example? Do you mean links that go from the docsite to the seL4 site, e.g. https://sel4.systems/Info/Docs/seL4-manual-latest.pdf?

I'd replace the links to forum, etc in the Resources section of the nav section on the left with a single link to a contact page

Done. I added a "contacts" section to the "Resources" front page, because this page already included links to mailing lists. "Contacts" now has links to mailing lists and forums.

Not sure the rename from "Getting Started" into "Working with seL4" is a success. The problem is more the content of that page, not so much what it is called ;-). In any case, "Working with seL4" is too long -- it line-breaks on narrower screens and looks bad when it does. Whatever name we pick should be narrower than the min size of the rest of the card on the front page. It'd be great to have an actual good Getting Started page, but that might lead a bit far astray from the purpose of this PR. I'd be fine with removing the links to that page from the top-level navigation and calling the heading on the front page "Resources" or something generic like that (without link to this specific page).

It's been renamed to "Resources." This page had an index page associated with it already. It's a bit verbose, but I mostly left it alone since it wasn't part of this PR. (I added a "forums" section, as described above.)

bbrcknl · 2024-07-18T22:31:53Z

Renaming the GettingStarted directory to Resources will break a number of links pointing to the docsite.

Repos that will need updating:

sel4/camkes-vm-examples-manifest
sel4/seL4
sel4/seL4_tools
sel4/sel4bench-manifest
sel4/sel4test-manifest
sel4/sel4test

While the renaming causes some pain, it may be worth doing since GettingStarted is an inaccurate name. (However it may be outside the scope of this PR.)

bbrcknl · 2024-07-29T02:38:29Z

@lsf37

a lot of the general menu links in unrelated parts of the site are now rendered as going off-site (probably just some small tweak somewhere, but needs to be fixed)

I changed template.py in seL4/sel4-tutorials#106 so that docsite links don't render as going offsite. This still needs further work. While the code works locally, it fails PR checks.

Makefile

Resources.md

Tutorials/capabilities.md

Tutorials/dynamic-1.md

Tutorials/how-to.md

Indanz · 2024-07-30T10:14:34Z

_includes/nav-sidebar.html

-  {% assign tutorials = site.pages | where_exp: 'page', 'page.tutorial' | sort: 'tutorial-order' %}
-  {% for t in tutorials %}
-        <li class="{% if page.url == t.url %}active{% endif %}">
-            <a class="" href="{{t.url}}">{{t.title}}</a>
-        <li>
-  {% endfor %}


So instead of a manually maintained index you can achieve the same with adding the category as a YAML header parameter which you query, or use other Jekyll features for collections like these. Perhaps something for the future.

I will need your help with this. The code deleted above was for ordering the tutorials on the old (current) docsite, which was pretty shoddy. I.e. the tutorial ordering made little sense, especially to the newbie.

The Jekyll way of doing this would be to make the tutorials a collection, add an ordering property to the YAML front matter and add a sort_by to the config file to order it by that.

But this only works if all items are files in the repo. If that's not the case, things get more messy and the best solution is less clear. Another downside is that there is no overview of the order and you need to see the rendered result.

For the website I added menu.json to have all metadata and ordering information in one place and used that as input to generate the wanted structure. The main reason I did it that way is to keep all the data compact with submenu support and in one place. It's also a mix of local and remote urls, so I couldn't add the metadata to front matter and I really didn't want to create shim files just for that as that's just messy.

Frankly, docs is a mess: It has all the tutorial shim files in the Tutorials directory which already contain a tutorial-order property, but it also added _data/projects/sel4-tutorials.yml. You only need one place to keep metadata.

What was wrong with the old code other than the order? The order can be changed by changing tutorial-order, it's probably alphabetically sorted by value. Main thing missing is the grouping you added, but that can be solved by adding a new field category to the first tutorial of each group: If set, generate a new '<li>'.

Once you know the order, it should also be possible to automatically generate the Next tutorial links too. Maintaining that manually will be hell and easy to forget when changing the order or adding new tutorials in the future.

You want to keep metadata out of your template code and you don't want the same metadata in multiple places.

There are additional menu items in the tutorial side bar that are a mix of external links and other pages on the site. It also has non-link section headers. The nicest way would probably be similar to what you did for the main site, with one separate json file that has the structure and a separate tutorials-nav include.

Hm. Nothing is ever simple. The sel4-tutorials.yml is currently there to define the "project", which has info that gets rendered on a bunch of overview pages, so we can't just remove it. We can use it to define the order, because it has an ordered list of all tutorial pages, and we can add additional info to each of the entries, but I'm not sure how to add additional info like section headers, external links, and links to other pages.

I guess, we could add another field "nav-section" to each component in there and then another top-level entry with a list of section headers, where each either has a nav section name or directly a list of nav items consisting of text and link. That could work. Not entirely sure I'll have time this afternoon, but I could give this a go.

I would go for the minimal change: Keep the non-tutorial links hard coded here for now and use the existing tutorial-order to generate the tutorial part, with a new property to create submenus. And then you can use that to figure out the next tutorial link too.

I couldn't get that quite working -- a lot of the hard coded part also needs to figure out "next" links, which is then not available as data. I went with something similar to the above, which removes a bit of the duplication (order and description in front matter) with sel4-tutorials.yml. The side bar works out ok, computing a reasonable "next" link did not end up to be very elegant.

Choosing the dict keys slightly differently would remove some of the case distinctions, but the ones prescribed by sel4-tutorials.yml sounded too nonsensical in the nav bar (name refers to file name, which I found most confusing in there. I guess display_name would be usable). The names in sel4-tutorials.yml are prescribed by other generic code on the site, so we can't tweak that without larger changes.

Anyway, have a look if the current version is acceptable. If not, we can always revert some of this.

I have not yet removed the manual "next" links for comparison. One thing that this brought up is that we have two "Overview" pages, which we should probably avoid.

_includes/nav-sidebar.html

assets/js/toggle-markdown.js

Hardware/IA32.md

_layouts/tutorial.html

_includes/header.html

Tutorials/get-the-tutorials.md

Indanz

You accidentally committed a conflicted merge, see <<<<<<<, >>>>>>> blocks.

lsf37 · 2024-07-31T22:47:17Z

You accidentally committed a conflicted merge, see <<<<<<<, >>>>>>> blocks.

Sorry about that, should now be fixed. Not sure how I managed to miss that one.

content_collections/_updates/sel4-tutorials/camkes-3.8.x.md

Indanz

Other than some nitpicks, all looks good.

Makefile

Tutorials/hello-world.md

Tutorials/index.md

_includes/header.html

assets/js/toggle-markdown.js

bbrcknl · 2024-10-04T08:06:08Z

Other than some nitpicks, all looks good.

Great, thanks for your review. I believe that all the outstanding issues have now been resolved.

Tutorials/how-to.md

Ivan-Velickovic · 2025-01-06T04:59:33Z

I get this when I try to build:

make[1]: *** No rule to make target '_repos/tutes/libraries-1.md', needed by 'tutorials'.  Stop.
make[1]: Leaving directory '/docs'

lsf37 · 2025-01-06T05:00:55Z

I get this when I try to build:

make[1]: *** No rule to make target '_repos/tutes/libraries-1.md', needed by 'tutorials'.  Stop.
make[1]: Leaving directory '/docs'

You need to manually set the right branch in the tutorials repo after it has pulled it, but before it builds it. It's unpleasant, but we're almost there.

lsf37 · 2025-01-06T05:01:49Z

The docsite should really be using a manifest and not just randomly clone things, but one thing at a time.

Ivan-Velickovic · 2025-01-06T05:02:19Z

Ah yes, thanks.

This commit should be read together with PR seL4/docs#231 The aim of both PRs was to arrange the tutorial material on the docsite such that it is clear and easy to follow. Inspired by the Rust book https://doc.rust-lang.org/book/, the user can see the chapters in the index on the left, and go straight to the corresponding tutorial sections. Specifically, the updates on the docsite provide: - 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 - The tutorials have been slightly rewritten to correct minor errors and provide inline solutions for readers wishing to understand the material and/or get quick solutions General changes in most files: - Make language and bullet points consistent; and, where required, add headers that can be referred to from how-to page - Add section on how to get tutorial solutions - Add inline tutorial solutions - Where necessary, add note that tutorial requires CapDL Loader, and instructions on how to get it. Specific files: macros.py: Remove help block, which was pointing to a list of contacts and resources. These are accessible via the updated tutorials nav sidebar. Rename get-the-code with the more specific get-the-tutorials. Add definition for accessing a tutorial with completed solutions. template.py: Add code to replace links to docsite (when tutorials are run in the docsite) with relative links. hello-world.md: Add more details on containers, builds and QEMU to ease the user into the tutorials. C Libraries: Generic change for C Libraries in the tutorials repo: C Libraries were previously called Dynamic Libraries, and filenames were dynamic-1 etc. There are now libraries-1 etc. hello-camkes-0.md: Add link to CAmkES tutorial slides camkes-vm-crossvm.md: Add note that tutorial instructions for this tutorial are only for Linux. Signed-off-by: Signed-off-by: Birgit Brecknell <[email protected]> Signed-off-by: Gerwin Klein <[email protected]>

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]>

lsf37

Now squashed into one commit and ready to go.

This commit should be read together with PR seL4/docs#231 The aim of both PRs was to arrange the tutorial material on the docsite such that it is clear and easy to follow. Inspired by the Rust book https://doc.rust-lang.org/book/, the user can see the chapters in the index on the left, and go straight to the corresponding tutorial sections. Specifically, the updates on the docsite provide: - 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 - The tutorials have been slightly rewritten to correct minor errors and provide inline solutions for readers wishing to understand the material and/or get quick solutions General changes in most files: - Make language and bullet points consistent; and, where required, add headers that can be referred to from how-to page - Add section on how to get tutorial solutions - Add inline tutorial solutions - Where necessary, add note that tutorial requires CapDL Loader, and instructions on how to get it. Specific files: macros.py: Remove help block, which was pointing to a list of contacts and resources. These are accessible via the updated tutorials nav sidebar. Rename get-the-code with the more specific get-the-tutorials. Add definition for accessing a tutorial with completed solutions. template.py: Add code to replace links to docsite (when tutorials are run in the docsite) with relative links. hello-world.md: Add more details on containers, builds and QEMU to ease the user into the tutorials. C Libraries: Generic change for C Libraries in the tutorials repo: C Libraries were previously called Dynamic Libraries, and filenames were dynamic-1 etc. There are now libraries-1 etc. hello-camkes-0.md: Add link to CAmkES tutorial slides camkes-vm-crossvm.md: Add note that tutorial instructions for this tutorial are only for Linux. Signed-off-by: Signed-off-by: Birgit Brecknell <[email protected]> Signed-off-by: Gerwin Klein <[email protected]>

bbrcknl changed the title ~~Reorganise tutorials and add inline solutions~~ DOCSITE: Reorganise tutorials and add inline solutions May 27, 2024

bbrcknl mentioned this pull request May 27, 2024

TUTORIALS: Reorganise tutorials and add inline solutions seL4/sel4-tutorials#106

Merged

lsf37 marked this pull request as ready for review July 8, 2024 02:50

lsf37 force-pushed the birg-tutorials-rework branch from d06f44d to cd043b6 Compare July 8, 2024 03:01