Preparing the local environment for writing documentation¶

Getting Started¶

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. If this is not your goal, you can edit the files Markdown directly on GitHub, open a PR with the changes, and the CI/CD pipeline will automatically build and deploy the website, once the PR is merged.

To write the content, we use Markdown with some extensions as described in the Material for MkDocs's reference.

In addition, we support the use of Juvix code examples in the files with the .juvix.md extension. These files are rendered using Juvix (+v0.6.6), and if you want to make sure that the code examples are correct, you must have Juvix installed on your machine. One way to do this is to install the Juvix plugin for VS Code from the marketplace.

Installing with Python¶

Install prerequisites

The following are the prerequisites to build the website locally:
- Python 3.9 or higher + pip: You can install it from here.
- To deploy the website locally, you would need to install graphviz to generate SVG files for dot files.
- As mentioned, we would need juvix to render the Juvix code examples.
Create a virtual environment
```
python3 -m venv env
```
Activate the virtual environment

Make sure to activate the virtual environment before proceeding. If you are using bash, you can do this by running:
```
source env/bin/activate
```
On fish, you can do this by running:
```
source env/bin/activate.fish
```
On zsh, you can do this by running:
```
source env/bin/activate
```
Install the required packages (preferably in the virtual environment) using Poetry:
```
pip3 install poetry
poetry install
```

Development shell with Nix¶

Install Nix: https://nixos.org/download/
Enable Nix Flakes: https://nixos.wiki/wiki/flakes
Enter development shell:
```
nix develop
```

Building the specs¶

To generate the website in the site/ directory, run:
```
mkdocs build
```
To serve the website locally, run the following command:
```
mkdocs serve
```
Take into account that this web server will automatically reload the website when you make changes to the files, and it is not especially fast.

Builds with quiet mode

By default, both `make build` or `make serve` are not configured to use the `--quiet` flag that suppresses the output of the build process, including warnings and errors. If you don't see all this output, you can run:

MKDOCSFLAGS=--quiet make build

make test-build