Editing the documentation¶

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 markdown file will be automatically rendered.

To add global css styling (using scss syntax), add a file into sass/ directory and import it in style.scss via @use 'myfile'. To add external javascript, e.g., in file.js file, simply create the file in docs/js/scripts/ and include it in the header of the corresponding markdown file:

---
scripts:
  - file
---

Some third-party libraries can be included on the given page in a similar way. Below is the full list of supported ones:

---
libraries:
  - d3 #(1)!
  - p5 #(2)!
  - mermaid #(3)!
  - three #(4)!
  - highlight #(5)!
  - tikzjax #(6)!
---

vector graphics, schemes and diagrams with d3js
interactive visualizations and easy WebGL access via p5js
rendering of mermaid diagrams
3D visualizations using WebGL in threejs
code highlighting with highlight.js
Tikz diagrams via TikzJax framework

Katex (for rendering \(\LaTeX\)) is automatically added to all pages.

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
```
Install all the node packages using (from the root directory):
```
npm i
```
If you don't have npm, try the following instruction.
Start the reactive server that will generate the website and will dynamically update any changes made to the documentation.
```
npm run dev
```
To access the documentation simply open the http://127.0.0.1:8000/ in your browser.

The npm command also compiles the sass styles into css, and minifies/copies the js libraries, placing them in the docs/js/vendor directory.
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.

Updating code structure diagrams and inputfile metadata

Some of the information on this website, such as the mermaid diagrams for the structure of classes in the code as well as the information about the latest input file are auto-generated using python scripts. To run the auto-generation to synchronize the wiki with the latest version of the code, simply run npm run inputtable:generate and/or npm run diagrams:generate. The script will automatically pull the latest version of the code from the master branch, generate the diagrams and the input metadata and put them in the assets/diagrams and assets/meta directory of the wiki repository.