User's documentation¶

For generating this user's documentation, we use zensical. Zensical is a modern static site generator designed to simplify building and maintaining project documentation.

Installation¶

Zensical is written in Rust and Python, and is published as a Python package. We recommend to use a Python virtual environment when installing with pip or with uv. Both options automatically install all necessary dependencies alongside Zensical.

Prerequisites

You need to have Python and a Python package manager installed on your system before you install Zensical. We recommend you follow the Python Setup and Usage instructions for your operating system provided on the Python website. Modern Python distributions include the pip package manager, so unless you are developing Python software and use uv, this is the simplest option to install Zensical on your system.

Install with pip¶

Zensical can be installed into a virtual environment with pip.

macOS Windows Linux

Open up a terminal window and install Zensical by first setting up a virtual environment and then using pip to install the Zensical package into it:

python3 -m venv .venv
source .venv/bin/activate
pip install zensical

Open up a Command Window and install Zensical by first setting up a virtual environment and then using pip to install the Zensical package into it:

python3 -m venv .venv
.venv\Scripts\activate
pip install zensical

Open up a terminal window and install Zensical by first setting up a virtual environment and then using pip to install the Zensical package into it:

python3 -m venv .venv
source .venv/bin/activate
pip install zensical

Install with uv¶

If you are developing software using Python, chances are you're already using uv as a package manager, which has become popular in recent years. To install Zensical with uv, use:

macOS Windows Linux

uv init
uv add zensical

uv init
uv add zensical

uv init
uv add zensical

Usage¶

The general command line syntax for Zensical is:

zensical COMMAND [OPTIONS] [ARGS]...

Commands¶

Help¶

General help: zensical --help
Command-specific help: zensical <command> --help

Preview¶

You can start a local web server to preview your documentation site as you write. This allows you to view your site in a web browser without deploying it to a remote server.

Use this command for preview only

Note that the web server that is built into Zensical is intended for preview purposes only. It is not designed for production deployment. We recommend to use a dedicated web server like nginx or Apache.

Usage¶

zensical serve [OPTIONS]

This starts a local web server that serves your documentation site on localhost:8000. As you make changes to source files, the browser will automatically reload the page you're on.

Options¶

The serve command accepts the following options:

Option	Short	Description
--config-file	-f	Path to the config file to use.
--open	-o	Open preview in default browser
--dev-addr <IP:PORT>	-a	IP address and port (default: localhost:8000)
--help		Show a help message and exit.

Build¶

To build your documentation site, run zensical build.

Usage¶

zensical build [OPTIONS]

This will generate the static site in the configured site_dir, with the default being site.

Options¶

You can run zensical build --help to get command-line help for the build command. It supports the following options:

Option	Short	Description
--config-file	-f	Path to the config file to use.
--clean	-c	Clean cache.
--help		Show a help message and exit.