Documentation functions¶
The documentation produced from the available functions is acceptable but what happens when a default value or example is a package?
Let us take a look by creating a new option in our options.nix file called randomPackage.
{
pkgs,
lib,
...
}: {
options = {
randomPackage = lib.mkOption {
type = lib.types.package;
default = pkgs.hello;
description = "A random package.";
example = pkgs.cowsay;
};
};
}
As before, we have a docs.nix file to create the CommonMark documentation.
{
nixpkgs ?
builtins.fetchTarball {
url = "https://github.com/NixOS/nixpkgs/tarball/aa94fc78b0a49ed2a4a69b6f5082a1b286dd392d";
sha256 = "1gkm7r07aqiyfgr32bzjmhvgsd543m2g3m43janmb6z1hz17ks1n";
},
pkgs ? import nixpkgs {},
}: let
evalOptions = (
pkgs.lib.evalModules {
modules = [
./options.nix
({...}: {config._module.args.pkgs = pkgs;})
];
}
);
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.
nix build -f docs.nix
If we run the script, we will produce an output in result that renders as follows.
randomPackage¶
A random package.
Type: package
Default:
<derivation hello-2.12.1>
Example:
<derivation cowsay-3.7.0>
Declared by: - /nix/store/acw2whabr474qk89dfb6mlsjlpk89n8m-source/documentation-functions/options.nix
That is not great. The default and example values refernece the derivations for those packages. However, we have some tools to help us produce better documentation.
Within mkOption, there is another attribute we can use defaultText which will replace default in the documentation.
This nicely separates default which is used for module evaluation from what appears in the documentation.
Example has no alternative value because it is purely used for documentation.
In addtion, we have two functions: literalExpression and literalMD.
literalExpression causes the given string to be rendered verbatim in the documentation as Nix code.
This is necessary for complex values, e.g. functions, or values that depend on other values or packages.
You could write in "pkgs.hello" but then the documention would render with the double quotes implying that it is a string.
Rather if we pass that string to literalExpression, the quotes are removed and the documentation renders it as code.
literalMD causes the given markdown text to be inserted verbatim in the documentation, for when a literalExpression would be too hard to read.
Examine our new options-fixed.nix file to see how we have implemented all of these new features to improve our module.
{
pkgs,
lib,
...
}: {
options = {
randomPackage = lib.mkOption {
type = lib.types.package;
default = pkgs.hello;
defaultText = lib.literalExpression "pkgs.hello";
description = "A random package.";
example = lib.literalMD "Any *random* **package**.";
};
};
}
We have a new docs-fixed.nix file to create the CommonMark documentation.
{
nixpkgs ?
builtins.fetchTarball {
url = "https://github.com/NixOS/nixpkgs/tarball/aa94fc78b0a49ed2a4a69b6f5082a1b286dd392d";
sha256 = "1gkm7r07aqiyfgr32bzjmhvgsd543m2g3m43janmb6z1hz17ks1n";
},
pkgs ? import nixpkgs {},
}: let
evalOptions = (
pkgs.lib.evalModules {
modules = [
./options-fixed.nix
({...}: {config._module.args.pkgs = pkgs;})
];
}
);
optionsDoc = (
pkgs.nixosOptionsDoc
{
options = builtins.removeAttrs evalOptions.options ["_module"];
}
);
in
optionsDoc.optionsCommonMark
We have a build-docs-fixed.sh script to help us build the docs.
nix build -f docs-fixed.nix
If we run the script, we will produce an output in result that renders as follows.
randomPackage¶
A random package.
Type: package
Default:
pkgs.hello
Example: Any random package.
Declared by: - /nix/store/acw2whabr474qk89dfb6mlsjlpk89n8m-source/documentation-functions/options-fixed.nix
Much better!