Documentation

There is a docs package which can be built as follows:

❯ nix build .#docs

This produces a static build of the docs and places it in a symlink called result in the same directory.

We can re-use this package as a devshell, relying upon it to provide the necessary dependencies for developing the docs.

{
  pkgs,
  perSystem,
  ...
}:
pkgs.stdenvNoCC.mkDerivation {
  name = "docs";

  src = ../../.;

  nativeBuildInputs =
    [
      perSystem.self.treefmt
    ]
    ++ (with pkgs.python3Packages; [
      mike
      mkdocs
      mkdocs-material
      mkdocs-awesome-pages-plugin
    ])
    ++ [
      (pkgs.writeShellApplication {
        name = "vhs";
        runtimeInputs =
          [
            perSystem.self.treefmt
            pkgs.rsync
            pkgs.vhs
          ]
          ++ (import ./treefmt/formatters.nix pkgs);
        text = ''vhs "$@"'';
      })
    ];

  buildPhase = ''
    cd docs
    mkdocs build
  '';

  installPhase = ''
    mv out $out
  '';
}

The docs are based on MkDocs and the MkDocs Material theme.

Serve locally

To serve the docs locally run mkdocs serve from the docs directory:

❯ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
WARNING -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - index.md
INFO    -  Documentation built in 0.26 seconds
INFO    -  [16:22:36] Watching paths for changes: 'docs/content', 'mkdocs.yml'
INFO    -  [16:22:36] Serving on http://127.0.0.1:8000/treefmt/

Versioning & Publication

Versioning of the docs is managed through mike.

It is responsible for managing the structure of the gh-pages branch in the repository, which Github Pages is configured to serve from.

Note

More information about versioning with MkDocs Material and mike can be found here.

There is a github workflow, .github/workflows/gh-pages.yml which is responsible for publishing the docs. It does the following:

• On merge to main, the docs version main is updated.
• When a new tag is created of the form v.<major>.<minor>.<patch> a docs version v<major>.<minor> is created and the latest alias is updated to point to this.

The idea is that users will land on the latest released version of the docs by default, with main being available if they wish to read about unreleased features and changes.

To preview the versions locally you can use mike serve instead of mkdocs serve.

Warning

Be sure to have fetched the latest changes for the gh-pages branch first. This is especially important if you are using mike locally to make manual changes to the published site.