TUTORIALS: Reorganise tutorials and add inline solutions #106
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The links in this PR fail because they refer to the new docsite layout, see seL4/docs#231 |
lsf37
reviewed
Jul 8, 2024
lsf37
reviewed
Jul 8, 2024
lsf37
reviewed
Jul 8, 2024
lsf37
reviewed
Jul 8, 2024
Indanz
requested changes
Jul 29, 2024
|
@Indanz |
|
Dynamic libraries filenames need changing. It's on my to-dos for Friday. |
lsf37
reviewed
Jul 31, 2024
bbrcknl
force-pushed
the
update_tutorials
branch
from
ed0c2e1 to
2955796
Compare
Indanz
approved these changes
Sep 30, 2024
lsf37
force-pushed
the
update_tutorials
branch
from
8acabc1 to
5c3b045
Compare
|
Squashed the commits as discussed on MM. Have a look if you're happy with the commit message. |
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]>
lsf37
force-pushed
the
update_tutorials
branch
from
5c3b045 to
7cd46c6
Compare
lsf37
pushed a commit
to bbrcknl/docs
that referenced
this pull request
Jan 6, 2025
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
approved these changes
Jan 6, 2025
lsf37
pushed a commit
to seL4/docs
that referenced
this pull request
Jan 6, 2025
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]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The updates in this PR were written in conjunction with those in seL4/docs#231
The aim of both PRs is:
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 sections that they need.
Specifically, the updates on the docsite provide:
The tutorials have been slightly rewritten to:
Remaining issues:
A note on using the rewritten docsite (from seL4/docs#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 seL4/docs#231
I can’t offer code for this because I’m a Makefile noob. I tested the new tutorials by having the Makefile call in and manipulate tutorial files from local directories.