Build Users Guide on NixOS

The guide is built with Sphinx -- a Python app. Unfortunately, there's a python dependency (sphinx-jsonschema) that is not in nixpkgs currently (June 2022). So, a havier approach than a simple nix-shell -p is needed.

shell.nix

let
  mach-nix = import (builtins.fetchGit {
    url = "https://github.com/DavHau/mach-nix";
    ref = "refs/heads/master";
  }) {};
in
mach-nix.mkPythonShell {
  requirements = builtins.readFile ./doc/requirements.txt;
}

Makefile-novenv

SPHINXCMD:=sphinx-build

# Flag -n ("nitpick") warns about broken references
# Flag -W turns warnings into errors
# Flag --keep-going continues after errors
SPHINX_FLAGS:=-n -W --keep-going -E
SPHINX_HTML_OUTDIR:=dist-newstyle/doc/users-guide

users-guide: doc/*.rst
	mkdir -p $(SPHINX_HTML_OUTDIR)
	$(SPHINXCMD) $(SPHINX_FLAGS) doc $(SPHINX_HTML_OUTDIR)

Build

$ nix-shell
$ make -f Makefile-novenv users-guide