Worked example

The following is an example of a complete project using UV and Make to create a simple documentation. Note the project is setup as a python project, however it is simply documentation.

Create the following 4 files in a folder (note the index.md file is in a subfolder)

pyproject.toml

[project]
name = "Demo-documentation"
version = "0.0.0"
dependencies = [
    "wj-mkdocs"
]

makefile

# Default target: print usage message
.PHONY: help
help:
    @echo "Usage:"
    @echo "  make docs         - Build HTML documentation"

# Version string from git tags
VERSION_STR=$(shell git describe --tags 2>/dev/null \
            | sed 's/-/.post.dev/' \
            | sed 's/-g/+/')

# Build the documentation
.PHONY: docs
docs: check-dependencies
    rm -rf html/
    VERSION=$(VERSION_STR) \
        uv run wj-mkdocs -f mkdocs.yml -d docs -o html

# Check if uv is installed, install it if not
.PHONY: check-dependencies
check-dependencies:
    uv version 2>/dev/null && true || pip3 install uv
    uv sync

Note the line starting VERSION_STR=... This uses git describe to get the version of the project. Any other method can be used and simply has to set the environment variable VERSION before calling wj-mkdocs

mkdocs.yml

INHERIT: !ENV THEME_STD
site_name: Demo Documentation

nav:
  - Home: index.md

docs/index.md

# Demo Documentation

This is a very simple example of using wj-mkdocs to generate documentation.

Building

Run the command

make docs

Almost every computer will have make already installed in the OS. This makefile only requires either uv is installed on the path, or if it is not then a working version of python3 (any version) with pip3.

uv ensures the correct versions of packages are installed and will install them in a virtual env.

Additionally uv creates a uv.lock file which fixes the versions of every package. This file should be put into source control to ensure all developers work in the same exact environment.

The output will be put into a folder html. This will be a fully self contained website that can be browsed directly from file system (open index.html) or hosted on any webserver.