Skip to content

Documentation

There is a separate devshell called docs which is provided for working with the docs locally.

It can be entered by running: nix develop .#docs

nix/devshells/docs.nix
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  pkgs,
  perSystem,
  ...
}:
pkgs.mkShellNoCC {
  packages = with pkgs;
  # Pop an empty shell on systems that aren't supported by godoc
    lib.optionals (perSystem.godoc ? default)
    ([
        perSystem.godoc.default
        (pkgs.writeScriptBin "gen-reference" ''
          out="./docs/content/reference/go_doc"
          godoc -c -o $out .
        '')
        (pkgs.writeScriptBin "mkdocs" ''
          # generate reference docs first
          gen-reference
          # execute the underlying command
          ${pkgs.mkdocs}/bin/mkdocs "$@"
        '')
      ]
      ++ (with pkgs.python3Packages; [
        mike
        mkdocs-material
      ]));
}

The docs are based on MkDocs and the MkDocs Material theme. You will find its configuration and content in the following locations:

  • mkdocs.yaml
  • ./docs

Serve locally

To serve the docs locally run mkdocs serve from the root of the repository:

1
2
3
4
5
6
7
8
❯ 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/nixos-facter/

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.