Skip to content

Preparing the local environment for writing documentation

Getting Started

Welcome to the Anoma Specs repository! This project uses Material for MkDocs for documentation and is designed for easy contribution and local development.

Quick Start

1. Prerequisites

Make sure you have the following tools installed:

  • uv (Python package/dependency manager)
    • macOS/Linux: 
      curl -LsSf https://astral.sh/uv/install.sh | sh
    • Windows: 
      powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    • Or via Homebrew: 
      brew install uv
  • graphviz (for local documentation deployment)
  • juvix (for typechecking and specs development) 
    curl --proto '=https' --tlsv1.2 -sSfL https://get.juvix.org | sh
  • just (a simple command runner, replacement for Make)

2. Installation

Choose one of the following:

  • With uv: 
    uv sync
  • With just: 
    just sync
  • With pip: 
    pip install -r requirements.txt

3. Common Commands

You can use either just or uv run for most tasks. Below are the most common commands:

Dependency Management

Task Command Command (just)
Synchronize dependencies uv sync just sync
Run all pre-commit checks uv run pre-commit -- run --all-files just check
Typecheck the code juvix typecheck docs/everything.juvix.md just juvix-check

Development Tools

  • Install pre-commit hooks (for specs writers only): 
    uv run pre-commit -- install --install-hooks
    or 
    just install-hooks
  • Install development tools: 
    uv tool install pre-commit
uv tool install commitizen
    or 
    just install-tools

Documentation

Task Command Command (just)
Build documentation uv run mkdocs build --config-file mkdocs.yml just build
Serve documentation locally uv run mkdocs serve --config-file mkdocs.yml just serve

Git Operations

Task Command Command (just)
Commit using commitizen uv run cz commit just commit
Commit skipping hooks git commit --no-verify -m "<msg>" just commit-skip
Amend commit (skip hooks) git commit --amend --no-verify just commit-amend
Amend using commitizen uv run cz commit --amend just cz-amend

If you have installed the pre-commit hooks (which is recommended), but need to make a commit or push changes without running the hooks (for example, when working on a branch or PR), you can use the --no-verify flag as shown in the table above. The Commitizen is a tool to help you write better commit messages.

4. Short Reference

  • Install: uv sync or pip install -r requirements.txt
  • Build: just build or uv run mkdocs build
  • Serve Locally: just serve or uv run mkdocs serve

Development with Nix

If you use Nix:

  1. Install Nix: Download
  2. Enable Flakes: Guide
  3. Enter Development Shell: 
    nix develop