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 viaTikzJax
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.
To access the documentation simply open thenpm run dev
http://127.0.0.1:8000/
in your browser.The
npm
command also compiles thesass
styles intocss
, and minifies/copies thejs
libraries, placing them in thedocs/js/vendor
directory. -
When satisfied with all the changes made simply push them to the
master
branch.Shortly after that,git add . git commit -m "<reasonable comment>" git push
github-actions
will generate the website and push it to thegh-pages
branch of the main repository, which will be accessible from the web.