Skip to content
This is the source of the seL4 docs.
C HTML Python CSS Makefile Ruby Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
CAmkES
CMA34DBMC
Developing/Building
Hardware
LevelConverter
Tutorials
VM
VisualCAmkES
_camkes_release
_data
_includes
_layouts
_plugins
_sel4_release
assets/css
dependencies
logos
seL4DriverAPI
tools
.gitignore
.gitmodules
404.html
ApiDoc.md
BenchmarkingGuide.md
CAmkESCLI.md
CAmkESDifferences.md
CAmkESInternals.md
CAmkESNext.md
CapDL.md Consistent code block ``` May 11, 2018
CodeReview.md
CommunityProjects.md
Conduct.md
Contributing.md
DebuggingGuide.md
DebuggingUserspace.md
Docker.md
DocsContributing.md
Documentation.md
FrequentlyAskedQuestions.md
Gemfile
Gemfile.lock
GettingStarted.md
GitConventions.md
HardwareHacks.md
HostDependencies.md
IRCChannel.md
LICENSE.txt
MaintainedRepositories.md
Makefile
PortingSeL4.md
README.md
ReleaseProcess.md
RepoCheatsheet.md
RfcProcess.md
Rust.md
SeL4Libraries.md
Status.md
StyleGuide.md
SuggestedProjects.md
UserlandComponents.md
_config.yml
favicon.ico
index.md
seL4ManualAPIGeneration.md
seL4SharedDataWithCaps.md
seL4Test.md
sitemap.md

README.md

seL4 Documentation site.

These are the sources for the seL4 Documentation site located at https://docs.sel4.systems. It is for cooperatively developing and sharing documentation on seL4.

See CONTRIBUTING.md for information on how to contribute. TL;DR click edit on the page in GitHub, make your changes and then submit a pull request.

Ask on the mailing list or open an issue if something doesn't make sense.

We've tried to make sure the hosted site is WCAG 2.0 AA compliant. Please let us know if we have missed something. This is how we test it.

Diagnosing a problem

Our documentation is contained in a collection of Markdown files stored in this repository. We use Jekyll to generate a static html website that is then hosted on GitHub pages. Our continuous integration is configured to regenerate and update the live site whenever a pull request is merged. There is a timestamp in the source that indicates when it was last generated. Additionally, each page has a timestamp and revision hash from when it was last updated located in the footer based on the git history.

Our markdown pages are rendered using Kramdown, a ruby based markdown converter that is configured to interpret the markdown files (.md) as GitHub flavoured markdown (GFM). We are currently using the jekyll-theme-bootstrap theme that provides a sass implementation of bootstrap. Our custom styling is contained in assets/css/style.scss. HTML templates are in either _layouts or _includes.

Requirements

Building the site

  • ruby-bundler must be installed

Linters

Linting checks require the linters to be installed.

  • HTML output checking using tidy: make check_html_output
  • Liquid syntax checking using liquid-linter: make check_liquid_syntax

Building the docsite

To build and host locally:

git submodule init
git submodule update

# If this doesn't work see: https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/
bundle install

bundle exec jekyll serve
#   Server address: http://127.0.0.1:4000/
#   Server running... press ctrl-c to stop.

Or with docker:

docker run --network=host -v $PWD:/host -w /host -it ruby bash -c 'bundle install && bundle exec jekyll serve'

Makefile and JEKYLL_ENV=production version

Jekyll provides an environment flag for providing some content only in a production environment.

One way we use this is to show data generated by rules in the Makefile and saved in _data/generated.yml. If you want to serve the site locally in production mode there are make rules for this. You will need to call the make rule to generate the _data/generated.yml also.

Quick compliance, style and formatting checks

WCAG 2.0 AA conformance

There is a make rule to check conformance to all testable statements from the guidelines. make check_conformance. It requires the site to be hosted locally (using make serve) and a local server of Automated Accessibility Testing Tool (AATT).

make check_conformance will output a file named conformance_results.xml which is a junit testsuite output file that will contain a testcase for each generated html file of the site. A make rule make check_conformance_errors will grep for failing testcases and output the html page name. The idea here is to detect if any pages are failing and then manually using the AATT tool's webinterface to check what parts of the page violate the guidelines.

You can’t perform that action at this time.