seL4 Documentation site.
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.
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
that provides a sass implementation of bootstrap. Our custom styling is contained in
HTML templates are in either _layouts or _includes.
Building the site
- ruby-bundler must be installed
Linting checks require the linters to be installed.
- HTML output checking using
- Liquid syntax checking using
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.
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.