https://github.com/sel4/docs
This is the source of the seL4 docs.
https://github.com/sel4/docs
documentation sel4
Last synced: 3 months ago
JSON representation
This is the source of the seL4 docs.
- Host: GitHub
- URL: https://github.com/sel4/docs
- Owner: seL4
- Created: 2018-03-22T05:20:08.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-04-25T03:14:00.000Z (3 months ago)
- Last Synced: 2025-04-25T04:23:27.015Z (3 months ago)
- Topics: documentation, sel4
- Language: C
- Homepage: https://docs.sel4.systems
- Size: 118 MB
- Stars: 16
- Watchers: 25
- Forks: 54
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSES/BSD-2-Clause.txt
Awesome Lists containing this project
README
# seL4 Documentation site
These are the sources for the seL4 Documentation site located at
. It is for cooperatively developing and sharing
documentation on [seL4](https://sel4.systems).
See [CONTRIBUTING.md](processes/docs-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][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](https://www.w3.org/TR/WCAG20/) compliant. Please let us know if we have
missed something.
[mailing-list]: https://lists.sel4.systems/postorius/lists/
## Building the site
### Install
#### Submodules
You need to run this only once after you have cloned this the repo.
```sh
git submodule init
git submodule update
```
#### Ruby
We recommend using [rbenv](https://github.com/rbenv/rbenv) to install the
correct Ruby version.
On Mac, using [homebrew](https://brew.sh):
```sh
brew install ruby-build rbenv
# follow the instructions this command shows, and start a new shell afterwards
rbenv init
# in the docs directory (root of this repo):
rbenv install
```
On apt-based Linux distributions (e.g. Ubuntu, Debian):
```sh
apt install rbenv
# follow the instructions this command shows, and start a new shell afterwards
rbenv init
# in the docs directory (root of this repo):
rbenv install
```
After these, you should be able to forget about `rbenv`, the `Makefile` will now
see the correct Ruby version.
#### Python
The build is tested with Python 3.9. More recent versions are likely to work as
well. After installing Python via e.g. `homebrew` or `apt`, you can install the
Python build dependencies with:
```sh
pip3 install --user camkes-deps
```
#### Linters
If you are using the lint checks, they require `tidy` and `liquid-linter`. If
you just want to build the site, you can skip these.
- HTML output checking using `tidy`: `make check_html_output`
- Liquid syntax checking using `liquid-linter`: `make check_liquid_syntax`
### Build
To build and host locally:
```sh
make serve
# Server address: http://127.0.0.1:4000/
# Server running... press ctrl-c to stop.
```
Or using Docker (you need [Docker
installed](https://docs.docker.com/get-docker/) and running for this):
```sh
make docker_serve
```
### Makefile and JEKYLL_ENV=production version
Jekyll environment flags can be used to provide 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.
## How the site is set up
Our documentation is contained in a collection of Markdown files stored in this
repository. We use [Jekyll](https://jekyllrb.com/) 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.
The markdown pages are rendered using
[Kramdown](https://kramdown.gettalong.org/), a ruby-based markdown converter
that is configured to interpret the markdown files (`.md`) as GitHub flavoured
markdown. 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`.
## 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)](https://github.com/paypal/AATT).
`make check_conformance` will output a file named `conformance_results.xml`
which is a junit test suite output file that will contain a test case for each
generated html file of the site. A make rule `make check_conformance_errors`
will grep for failing test cases 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
web interface to check what parts of the page violate the guidelines.