Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCSITE: Reorganise tutorials and add inline solutions #231

Open
wants to merge 112 commits into
base: master
Choose a base branch
from
Open
Changes from 1 commit
Commits
Show all changes
112 commits
Select commit Hold shift + click to select a range
502c045
add new structure for tutorials
bbrcknl Mar 1, 2024
3321716
add about seL4 text
bbrcknl Mar 1, 2024
ca73b83
minor update microkit page
bbrcknl Mar 1, 2024
cd889c4
rewrite tuts (incomplete)
bbrcknl Mar 4, 2024
0d7dc88
add reordered tutorial sidebar
bbrcknl Mar 4, 2024
c6e88b0
fix nav-sidebar
bbrcknl Mar 4, 2024
85b9591
rework tuts (incomplete); update navbar
bbrcknl Mar 4, 2024
f918f4a
add reworked tuts (incomplete)
bbrcknl Mar 6, 2024
fa1c85d
add reworked tuts (incomplete)
bbrcknl Mar 8, 2024
a311549
add how-to page
bbrcknl Mar 11, 2024
cb2fc67
add camkes 1 and 2 (incomplete)
bbrcknl Mar 11, 2024
9007734
update camkes 1 and 2 (incomplete)
bbrcknl Mar 11, 2024
8f11ebd
add and update camkes 2 & 3 tuts
bbrcknl Mar 13, 2024
a18f827
update camkes tuts
bbrcknl Mar 15, 2024
d63b96f
add tutorials overview page
bbrcknl Mar 15, 2024
6e8dbed
add resources
bbrcknl Mar 15, 2024
e293afc
add more resources
bbrcknl Mar 15, 2024
84168b0
replace old tut files with new
bbrcknl Mar 15, 2024
c9aaf62
change Getting Started to Working with seL4
bbrcknl Mar 15, 2024
442aacb
work on redirect for tutorial landing page
bbrcknl Mar 15, 2024
ce25b3f
organise front page, navbar and how-to page
bbrcknl Mar 18, 2024
dae73c8
fix trailing whitespace
bbrcknl Mar 18, 2024
4bfd6d9
fix broken links
bbrcknl Mar 22, 2024
1769b62
add layout for tutorial pages
bbrcknl Mar 22, 2024
98b162c
update setting up instructions
bbrcknl Apr 19, 2024
7071759
rename tutorials to match tutorials repo
bbrcknl Apr 24, 2024
438d54a
add tests for including tutorial.md
bbrcknl May 10, 2024
5fbdc58
revert docsite tutorial files to include tutes from tutorials repo
bbrcknl May 13, 2024
94045ff
fix links in nav sidebar
bbrcknl May 13, 2024
5e86114
Makefile testing code
bbrcknl May 27, 2024
104f7d0
add refs and headers to how-to page
bbrcknl May 17, 2024
4758f09
fix typo
bbrcknl May 17, 2024
c22a3e6
fix href target blank
bbrcknl May 17, 2024
61f321c
fix link
bbrcknl May 17, 2024
cd34825
expand solutions if using how-to page
bbrcknl May 20, 2024
74e0413
add css space after solution boxes
bbrcknl May 20, 2024
f159026
separate instructions for getting tutes manifest
bbrcknl May 20, 2024
afc4010
fix fault handlers link
bbrcknl May 24, 2024
8af55ad
update mcs link in fault handlers tut
bbrcknl May 24, 2024
264bdc4
add item to how-to page
bbrcknl May 27, 2024
3ecb6fa
fix whitespace error
bbrcknl May 27, 2024
43542f4
remove testing code from Makefile
bbrcknl May 27, 2024
94fe1fc
add licence to toggle-markdown.js
bbrcknl May 27, 2024
ba70bbe
remove old tutorial files
bbrcknl May 27, 2024
d3ba4f8
Update Tutorials/seL4Kernel/setting-up.md
bbrcknl Jul 10, 2024
0556ae4
Update Tutorials/seL4Kernel/setting-up.md
bbrcknl Jul 10, 2024
d28d363
Update Tutorials/seL4Kernel/setting-up.md
bbrcknl Jul 10, 2024
68c00ea
address Gerwin's high level comments (incomplete)
bbrcknl Jul 12, 2024
28d8d6d
work (incomplete) on tutorial pathways
bbrcknl Jul 12, 2024
51ad641
finish adding tutorial pathways
bbrcknl Jul 14, 2024
9b3284c
finish addressing Gerwin high-level issues
bbrcknl Jul 14, 2024
5e641fb
move toggle markdown to tutorial layout
bbrcknl Jul 14, 2024
cd0344e
fix trailing whitespace
bbrcknl Jul 14, 2024
e8ff93d
fix mattermost link
bbrcknl Jul 14, 2024
42b9c6c
address Gerwin's comments on setting-up page
bbrcknl Jul 15, 2024
6502de9
put dependencies in one line of code
bbrcknl Jul 15, 2024
c6d7a3a
fix links
bbrcknl Jul 15, 2024
3e2f994
revert to old tutorials structure
bbrcknl Jul 17, 2024
aa1e4d1
move how-to to tutorials dir
bbrcknl Jul 18, 2024
127113e
change old GettingStarted links to Resources
bbrcknl Jul 18, 2024
a134caf
add how-to to tutorials in makefile
bbrcknl Jul 18, 2024
9dd38d1
fix code in capabilities tut
bbrcknl Jul 19, 2024
0bb322a
fix path in toggle-markdown for tutes
bbrcknl Jul 19, 2024
6ff3c1a
fix typo
bbrcknl Jul 26, 2024
eb0932b
remove trace from Makefile
bbrcknl Jul 31, 2024
da53f84
fix typo Resources.md
bbrcknl Jul 31, 2024
4655aad
fix copyright year - capabilities
bbrcknl Jul 31, 2024
4791ced
remove empty lines - dynamic-1
bbrcknl Jul 31, 2024
203a9f8
fix typos in how-to
bbrcknl Jul 31, 2024
9eafb8a
fix mcs description
bbrcknl Jul 31, 2024
aefbaab
fix copyright year pathways and overview
bbrcknl Jul 31, 2024
4fd520d
minor fixes navbar
bbrcknl Jul 31, 2024
02f9734
replace dynamic-libraries with libraries
bbrcknl Jul 31, 2024
2debab4
replace dynamic libraries with libraries
bbrcknl Jul 31, 2024
fc11969
nav: fix project links
lsf37 Jul 31, 2024
ce0ef6d
nav: tweak sections in tutorial nav
lsf37 Jul 31, 2024
7a0599d
[drop] temporarily revert library rename
lsf37 Aug 1, 2024
f635bf1
tutorials: remove unused front matter description
lsf37 Aug 1, 2024
b787447
tutorial nav: factor out tutorial navigation
lsf37 Aug 1, 2024
35dd737
layouts/tutorial: remove unused code
lsf37 Aug 1, 2024
9aa4207
layout/tutorials: tweak js link
lsf37 Aug 1, 2024
a50cf29
debugging-guide: use tutorial layout
lsf37 Aug 1, 2024
1e2e4b1
tutorials: remove unused tutorial-order field
lsf37 Aug 1, 2024
09108e1
tutorials: redirect /projects/sel4-tutorials/
lsf37 Aug 1, 2024
34f5313
tutorial nav: automate "next" link
lsf37 Aug 1, 2024
48dbb59
tutorial nav: move "included from" to layout
lsf37 Aug 1, 2024
99ae7a4
Update Tutorials/get-the-tutorials.md
bbrcknl Aug 9, 2024
5578b97
Update Tutorials/get-the-tutorials.md
bbrcknl Aug 9, 2024
c4e61e4
Update Tutorials/get-the-tutorials.md
bbrcknl Aug 9, 2024
ba83f25
Update Tutorials/get-the-tutorials.md
bbrcknl Aug 9, 2024
448e41c
rename dynamic to libraries
bbrcknl Aug 9, 2024
1903f1c
fix accidental renaming in IA32.md
bbrcknl Aug 9, 2024
04c005a
change name dynamic -> libraries
bbrcknl Aug 9, 2024
8a3bc44
change dir tutorials -> Tutorials
bbrcknl Aug 9, 2024
5336a78
change libraries->dynamic in old release notes
bbrcknl Aug 11, 2024
06e6c24
consolidate two tutorials overview pages
bbrcknl Aug 12, 2024
07952f1
remove next link for external tutes
bbrcknl Aug 23, 2024
ad85e98
remove duplicate next links
bbrcknl Aug 23, 2024
6505987
fix solutions css styling and pointer
bbrcknl Aug 23, 2024
fd00916
fix pointer for expanded solutions box
bbrcknl Aug 23, 2024
fa69841
Merge branch 'master' into birg-tutorials-rework
bbrcknl Aug 23, 2024
6e5059f
remove accidental commit of camkes-vm
bbrcknl Aug 23, 2024
7620007
remove breadcrumb naming hack
bbrcknl Aug 26, 2024
bcbc394
update camkes and library headers
bbrcknl Aug 26, 2024
238fb77
remove duplicated next link
bbrcknl Sep 27, 2024
c6adfe6
add comment about filtered tut pages
bbrcknl Oct 4, 2024
6258219
revert copyright year
bbrcknl Oct 4, 2024
e20dd47
add relative_url for github preview
bbrcknl Oct 4, 2024
a2a59cd
fix js code for markdown expansions
bbrcknl Oct 4, 2024
0bc8c02
Fix Tutorial How To Links
Indanz Oct 4, 2024
5fc2d96
fix typo
bbrcknl Nov 3, 2024
1eb12d5
add descriptions to tutorial files
bbrcknl Nov 4, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
tutorial nav: factor out tutorial navigation
- put tutorial nav bar into own include file to remove complexity from
  nav-sidebar.html

- add tutorials-sidebar.yml for nav content, with references to
  sel4-tutorials.yml for actual tutorial files.

- arrange order, display names, and section categories in
  sel4-tutorials.yml for nav bar.

Signed-off-by: Gerwin Klein <gerwin.klein@proofcraft.systems>
lsf37 committed Aug 1, 2024
commit b787447aa0e0263649ec97eb7e67a7b3e86f5b17
148 changes: 96 additions & 52 deletions _data/projects/sel4-tutorials.yml
Original file line number Diff line number Diff line change
@@ -12,127 +12,171 @@ repositories:
- org: sel4proj
repo: sel4-tutorials-manifest

# The order of the components list determines the order of the tutorials in the
# tutorial nav side bar. The field section is used there to include groups of
# tutorials.

components:
- name: hello-world
display_name: "Hello world"
description: "The first seL4 application to run"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: hello-camkes-0
display_name: "CAmkES"
description: "The first CAmkES application to run"
section: sel4

- name: capabilities
display_name: "Capabilities"
description: "seL4 capabilities tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: hello-camkes-1
display_name: "CAmkES 1"
description: "CAmkES ADL and RPC interface tutorial"
section: sel4

- name: untyped
display_name: "Untyped"
description: "Physical memory management tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: hello-camkes-2
display_name: "CAmkES 2"
description: "CAmkES event and dataport tutorial"
section: sel4

- name: mapping
display_name: "Mapping"
description: "Virtual memory management tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: hello-camkes-timer
display_name: "CAmkES timer"
description: "CAmkES tutorial for accessing hardware"
section: sel4

- name: threads
display_name: "Threads"
description: "Threads on seL4 tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: libraries-1
display_name: "Dynamic Libraries 1"
description: "Initialisation and threading tutorial"
section: sel4

- name: ipc
display_name: "IPC"
description: "seL4 IPC tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: libraries-2
display_name: "Dynamic Libraries 2"
description: "seL4 IPC and userspace paging management tutorial"
section: sel4

- name: notifications
display_name: "Notification"
description: "seL4 notification tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: libraries-3
display_name: "Dynamic Libraries 3"
description: "Processes and ELF loading tutorial"
section: sel4

- name: interrupts
display_name: "Interrupts"
description: "Tutorial for accessing interrupts on seL4"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: libraries-4
display_name: "Dynamic Libraries 4"
description: "Tutorial for using device drivers"
section: sel4

- name: fault-handlers
display_name: "Fault handling"
description: "Fault handling tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
section: sel4

- name: mcs
display_name: "MCS"
display_name: "MCS Extensions"
description: "MCS extension tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: capabilities
display_name: "Capabilities"
description: "seL4 capabilities tutorial"
section: sel4

- name: dynamic-1
display_name: "Initialisation &amp; threading"
description: "Initialisation and threading tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: untyped
display_name: "Untyped"
description: "Physical memory management tutorial"
section: libraries

- name: dynamic-2
display_name: "IPC"
description: "seL4 IPC and userspace paging management tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: mapping
display_name: "Mapping"
description: "Virtual memory management tutorial"
section: libraries

- name: dynamic-3
display_name: "Processes &amp; Elf loading"
description: "Processes and ELF loading tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: threads
display_name: "Threads"
description: "Threads on seL4 tutorial"
section: libraries

- name: dynamic-4
display_name: "Timer"
description: "Tutorial for using device drivers"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: ipc
display_name: "IPC"
description: "seL4 IPC tutorial"
section: libraries

- name: hello-camkes-0
display_name: "Hello CAmkES"
description: "The first CAmkES application to run"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: notifications
display_name: "Notification"
description: "seL4 notification tutorial"
section: camkes

- name: hello-camkes-1
display_name: "CAmkES 1: Introduction to CAmkES"
description: "CAmkES ADL and RPC interface tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: interrupts
display_name: "Interrupts"
description: "Tutorial for accessing interrupts on seL4"
section: camkes

- name: hello-camkes-2
display_name: "CAmkES 2: Events"
description: "CAmkES event and dataport tutorial"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
- name: fault-handlers
display_name: "Fault handling"
description: "Fault handling tutorial"
section: camkes

- name: hello-camkes-timer
display_name: "CAmkES 3: Timer"
description: "CAmkES tutorial for accessing hardware"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
section: camkes

- name: camkes-vm-linux
display_name: "CAmkES VM Linux"
display_name: "CAmkES VM"
description: "Tutorial for creating VM guests and applications on seL4 using CAmkES"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
section: camkes

- name: camkes-vm-crossvm
display_name: "CAmkES cross-VM communication"
description: "Tutorial for using cross virtual machine connector"
display_name: "CAmkES Cross-VM Connectors"
description: "Tutorial for using cross virtual machine connectors"
maintainer: "seL4 Foundation"
status: "active"
component_type: sel4-tutorials-application
section: camkes

- name: libsel4tutorials
display_name: "libsel4tutorials"
description: "Utility Library for doing seL4 tutorials"
70 changes: 70 additions & 0 deletions _data/tutorials-sidebar.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# SPDX-License-Identifier: CC-BY-SA-4.0
# Copyright 2024 seL4 Project a Series of LF Projects, LLC.

# nav side bar for tutorials
#
# refers to sections from projects/sel4-tutorials.yml via the "section" field
# there, and "include" field here.

- name: Getting started
type: header
- name: Overview of tutorials
file: ""
type: file
- name: Tutorial pathways
file: pathways
type: file

- name: seL4
type: header
- name: Overview
file: sel4-overview
type: file
- name: Setting up your machine
file: setting-up
type: file
- name: Getting the tutorials
file: get-the-tutorials
type: file
- name: sel4
type: include

- name: C Libraries
type: header
- name: libraries
type: include

- name: Microkit
type: header
- name: Tutorial
url: https://trustworthy.systems/projects/microkit/tutorial/
type: url

- name: CAmkES
type: header
- name: camkes
type: include

- name: Rust
type: header
- name: GitHub
url: https://github.com/seL4/rust-sel4
type: url

- name: Resources
type: header
- name: seL4 Manual
url: https://sel4.systems/Info/Docs/seL4-manual-latest.pdf
type: url
- name: seL4 API reference
url: /projects/sel4/api-doc.html
type: url
- name: "How to: a quick solutions guide"
file: how-to
type: file
- name: Debugging guide
url: /projects/sel4-tutorials/debugging-guide
type: url
- name: Help contacts
url: "/Resources#contact"
type: url
44 changes: 0 additions & 44 deletions _includes/nav-sidebar.html
Original file line number Diff line number Diff line change
@@ -54,48 +54,4 @@
</ul>
{% endif %}

{% if page_url[1] == "Tutorials" %}
{% assign url = "" %}
<ul class="nav nav-sidebar tutorial-sidebar">
<li class="nav-section">Getting started</li>
<li><a href="{{url}}/tutorials/">Overview of tutorials</a></li>
<li><a href="{{url}}/tutorials/pathways">Tutorial pathways</a></li>
<li class="nav-section">seL4</li>
<li><a href="{{url}}/tutorials/sel4-overview">Overview</a></li>
<li><a href="{{url}}/tutorials/setting-up">Setting up your machine</a></li>
<li><a href="{{url}}/tutorials/get-the-tutorials">Getting the tutorials</a></li>
<li><a href="{{url}}/tutorials/hello-world">Hello world</a></li>
<li><a href="{{url}}/tutorials/capabilities">Capabilities</a></li>
<li><a href="{{url}}/tutorials/untyped">Untyped</a></li>
<li><a href="{{url}}/tutorials/mapping">Mapping</a></li>
<li><a href="{{url}}/tutorials/threads">Threads</a></li>
<li><a href="{{url}}/tutorials/ipc">IPC</a></li>
<li><a href="{{url}}/tutorials/notifications">Notifications</a></li>
<li><a href="{{url}}/tutorials/interrupts">Interrupts</a></li>
<li><a href="{{url}}/tutorials/fault-handlers">Fault Handling</a></li>
<li><a href="{{url}}/tutorials/mcs">MCS Extensions</a></li>
<li class="nav-section">Dynamic libraries</li>
<li><a href="{{url}}/tutorials/dynamic-1">Initialisation &amp; threading</a></li>
<li><a href="{{url}}/tutorials/dynamic-2">IPC</a></li>
<li><a href="{{url}}/tutorials/dynamic-3">Processes &amp; Elf loading</a></li>
<li><a href="{{url}}/tutorials/dynamic-4">Timer</a></li>
<li class="nav-section">Microkit</li>
<li><a href="https://trustworthy.systems/projects/microkit/tutorial/">Tutorial</a></li>
<li class="nav-section">CAmkES</li>
<li><a href="{{url}}/tutorials/hello-camkes-0">Hello CAmkES</a></li>
<li><a href="{{url}}/tutorials/hello-camkes-1">CAmkES 1: Introduction to CAmkES</a></li>
<li><a href="{{url}}/tutorials/hello-camkes-2">CAmkES 2: Events</a></li>
<li><a href="{{url}}/tutorials/hello-camkes-timer">CAmkES 3: Timer</a></li>
<li><a href="{{url}}/tutorials/camkes-vm-linux">CAmkES VM</a></li>
<li><a href="{{url}}/tutorials/camkes-vm-crossvm">CAmkES Cross VM Connectors</a></li>
<li class="nav-section">Rust</li>
<li><a href= "https://github.com/seL4/rust-sel4">GitHub</a></li>
<li class="nav-section">Resources</li>
<li><a href="https://sel4.systems/Info/Docs/seL4-manual-latest.pdf">seL4 Manual</a></li>
<li><a href= "/projects/sel4/api-doc.html">API references</a></li>
<li><a href="{{url}}/tutorials/how-to"><em>How to:</em> A quick solutions guide</a></li>
<li><a href="../projects/sel4-tutorials/debugging-guide">Debugging guide</a></li>
<li><a href="../Resources#contact">Contact</a></li>
</ul>
{% endif %}
</div>
28 changes: 28 additions & 0 deletions _includes/tutorials-sidebar.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{% comment %}
SPDX-License-Identifier: CC-BY-SA-4.0
SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC.
{% endcomment %}

<div class="sidebar">
<ul class="nav nav-sidebar tutorial-sidebar">
{%- for item in site.data.tutorials-sidebar -%}
{%- case item.type -%}
{%- when "header" %}
<li class="nav-section">{{ item. name}}</li>
{%- when "file" -%}
{%- assign url = "/Tutorials/" | append: item.file | relative_url %}
<li><a href="{{ url }}">{{ item.name }}</a></li>
{%- when "url" %}
<li><a href="{{ item.url | relative_url }}">{{ item.name }}</a></li>
{%- when "include" -%}
{%- assign components = site.data.projects["sel4-tutorials"].components -%}
{%- for component in components -%}
{%- if component.section == item.name -`%}
{%- assign url = "/Tutorials/" | append: component.name | relative_url %}
<li><a href="{{ url }}">{{ component.display_name }}</a></li>
{%- endif -%}
{%- endfor -%}
{%- endcase -%}
{%- endfor %}
</ul>
</div>
3 changes: 1 addition & 2 deletions _layouts/tutorial.html
Original file line number Diff line number Diff line change
@@ -6,8 +6,7 @@

<div class="row">
<div class="hidden-xs col-sm-4 col-md-3 col-lg-2">
{% include nav-sidebar.html %}

{% include tutorials-sidebar.html %}
</div>
<div class="content col-sm-8 col-md-6 col-lg-7 main">
{{ content }}