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