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: https://github.com/seL4/sel4-tutorials/pull/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 https://github.com/seL4/docs/pull/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]

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

[bbrcknl]

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

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]

@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 https://github.com/seL4/sel4-tutorials/pull/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.

[lsf37]

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

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

[bbrcknl]

Other than some nitpicks, all looks good.

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

[Ivan-Velickovic]

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]

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]

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

[Ivan-Velickovic]

Ah yes, thanks.