If you are looking for documentation of our LITTIL platform, then please visit our documentation site. If you have run into a problem on our LITTIL platform, please submit an issue on GitHub in order for our contributers can have a look.
If you are interested in contributing to our documentation then please read the instructions below and have a look at how you can contribute. Our documentation, which is published via GitHub pages, is generated with MkDocs (with a custom material theme). You can find instructions below about writing documentation, previewing and building the documentation.
We created a custom image which includes all tools needed to write documentation using MkDocs, Markdown and PlantUML. Because of this, you only need docker installed on your machine when writing and building documentation locally. You can find instructions here on how to install docker on your machine.
If you are in need to install an extra plugin for example, you can create a new image using the Dockerfile located at:
./Dockerfile. Alter the file accordingly and then run:
$ docker build . -t <new_tag>When you want to preview the documentation site locally you can use the same Docker container which is used to build
the documentation. Run the following command in the root of the project to preview the new documentation site.
$ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs -e ENABLE_GIT_INTEGRATION=False ghcr.io/devoxx4kids-npo/littil-documentation:latestor if you want to use docker compose
$ docker compose upThe documentation site should be available at http://localhost:8000.
You can also use your local build image by changing the last parameter with the tag you used.
Building the documentation site is done via the GitHub Actions when merging the documentation to the trunk repository. Though, if you are in need to inspect the generated site artifacts you can run the following command.
$ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs -e ENABLE_GIT_INTEGRATION=False ghcr.io/devoxx4kids-npo/littil-documentation:latest buildThe generated artifacts are located in the directory ./site. Make sure you do not commit this directory to the repository.
If you want to alter the theme of the documentation site you have 2 options. When only changing colors you can enhance
the file ./docs/stylesheets/extra.css. The littil theme itself is located at ./docs/theme/littil-theme. Follow the
guide of MkDocs Material on how to overwrite the theme.
The template has several plugins which uses the GitHub API anonymously. Only in build stage we have a GitHub token available
to communicate with GitHub authenticated. This anonymous integration has a limit rating which you can hit when writing documentation
locally. To disable the Git features you should start the container with the environment variable ENABLE_GIT_INTEGRATION
set to False. Starting the container without the variable or with the value set to True will enable the features.
To create or alter the menu you need to alter the tile ./mkdocs.yml in the root of the project. The rest of the documentation
is written in regular Markdown files. Please read the following instructions
for more details.
This documentation site supports PlantUML to draw diagrams as code. During the generation of the site it will look for
files within the directory ./docs/diagrams/src.Generated diagrams are stored in the directory ./docs/diagrams/out
in SVG format to which you can refer to in your markdown pages as an image.
In example: .
Please see the plugin repository for more detailed instructions.