DOCSITE: Reorganise tutorials and add inline solutions

[bbrcknl]

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]

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]

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

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]

(rebased to more easily see the new commits)

[lsf37]

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).

[lsf37]

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.

[bbrcknl]

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

[lsf37]

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

[bbrcknl]

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.

[lsf37]

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.

[bbrcknl]

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?

[lsf37]

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

[lsf37]

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

[Indanz]

Other than some nitpicks, all looks good.

[Indanz]

This one is still unresolved.

[bbrcknl]

Other than some nitpicks, all looks good.

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