Documenting

entity documentation is automatically generated using the mkdocs framework and the Material for mkdocs theme. When you commit/push to the wiki branch the static website is automatically compiled and pushed to the gh-pages branch of the main repository.

Hint

Documentations are created using markdown syntax which is then automatically parsed and converted into html. As such, any html/css/js code you write in the documentation will be automatically rendered in the documentation. To add global external css or js files, add them to the mkdocs.yml file (extra_javascript and extra_css). If a script is meant to run on just one page, add it with a dedicated <script></script> tag.

Workflow¶

Pull the wiki branch of the main repository (it is recommended to do this in a separate directory from the main code).
```
git clone git@github.com:entity-toolkit/wiki.git entity-wiki
cd entity-wiki
```
Create an isolated python virtual environment and activate it.
```
python -m venv .venv
source .venv/bin/activate
```
Install the dependencies (everything is installed locally in the .venv directory).
```
pip install -r requirements.txt
```
Start the reactive server that will generate the website and will dynamically update any changes made to the documentation.
```
mkdocs serve
```
To access the documentation simply open the http://127.0.0.1:8000/ in your browser.
When satisfied with all the changes made simply push them to the master branch.
```
git add .
git commit -m "<reasonable comment>"
git push
```
Shortly after that github-actions will generate the website and push it to the gh-pages branch of the main repository, which will be accessible from the web.