Installation and setup

Rustemo uses Nix package manager to setup reproducible documentation development environment locally.

  1. Install Nix
  2. Enable flakes
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
  1. From the root of the project run:
nix develop
mdbook serve docs

The docs will be available at http://localhost:3000/ and the server will watch for changes and rebuild.

Nix-based shell has an added benefix that it provides all additional required dependencies (e.g. pdflatex and required package for building tree images, plantuml, graphviz). E.g., to rebuild tree images from .tex files you can run docs/build-latex-images.sh (it is automatically called by mdbook serve docs, see Trees diagrams bellow).

Admonitions

This doc uses mdbook-admonish pre-processor. See here.

Including files

Including files ensure that the docs is up-to-date with the content it is referring to.

See this part of the manual.

Cross references

See this on how to reference to other section of the document.

Diagrams

For UML diagrams we use PlantUML, while for general graphs and trees GraphViz is used.

Trees diagrams

For tree diagrams LaTeX (pdflatex) with qtree package is used to produce PDF and afterwards the PDF file is converted to PNG using pdftoppm. See docs/build-latex-images.sh script. This script must be called whenever .tex files with trees description are changed.