Option documentation

As you start creating option declarations, it is important to document them. In addition to type and default, there are two other attributes available that will appear in generated documentation, description and example.

In options.nix, we have a option declared, name, and we have set the attributes for description and example.

options.nix

{lib, ...}: {
  options = {
    name = lib.mkOption {
      type = lib.types.str;
      default = "";
      description = "A name for a user.";
      example = "Boaty McBoatface";
    };
  };
}

To generate documentation, we will use another function from nixpkgs, nixosOptionsDoc. In docs.nix, we evaluate our modules with evalModules as we have done previously. That is passed to the nixosOptionsDoc function as the options attribute. nixosOptionsDoc produces documentation in many forms: JSON, AsciiDoc, and CommonMark. For this lesson, we will look at CommonMark.

docs.nix

{
  nixpkgs ?
    builtins.fetchTarball {
      url = "https://github.com/NixOS/nixpkgs/tarball/aa94fc78b0a49ed2a4a69b6f5082a1b286dd392d";
      sha256 = "1gkm7r07aqiyfgr32bzjmhvgsd543m2g3m43janmb6z1hz17ks1n";
    },
  pkgs ? import nixpkgs {},
}: let
  evalOptions = (
    pkgs.lib.evalModules {
      modules = [
        ./options.nix
      ];
    }
  );
  optionsDoc = (
    pkgs.nixosOptionsDoc
    {
      options = builtins.removeAttrs evalOptions.options ["_module"];
    }
  );
in
  optionsDoc.optionsCommonMark

We have a build-docs.sh script to help us build the docs.

build-docs.sh

nix build -f docs.nix

If we run the script, we will produce an output in result that renders as follows.

---

name

A name for a user.

Type: string

Default: ""

Example: "Boaty McBoatface"

Declared by: - /nix/store/acw2whabr474qk89dfb6mlsjlpk89n8m-source/option-documentation/options.nix

---