pyrox.dev
1/**
2 Generates documentation for [nix modules](https://nix.dev/tutorials/module-system/module-system.html).
3
4 It uses the declared `options` to generate documentation in various formats.
5
6 # Outputs
7
8 This function returns an attribute set with the following entries.
9
10 ## optionsCommonMark
11
12 Documentation in CommonMark text format.
13
14 ## optionsJSON
15
16 All options in a JSON format suitable for further automated processing.
17
18 `example.json`
19 ```json
20 {
21 ...
22 "fileSystems.<name>.options": {
23 "declarations": ["nixos/modules/tasks/filesystems.nix"],
24 "default": {
25 "_type": "literalExpression",
26 "text": "[\n \"defaults\"\n]"
27 },
28 "description": "Options used to mount the file system.",
29 "example": {
30 "_type": "literalExpression",
31 "text": "[\n \"data=journal\"\n]"
32 },
33 "loc": ["fileSystems", "<name>", "options"],
34 "readOnly": false,
35 "type": "non-empty (list of string (with check: non-empty))"
36 "relatedPackages": "- [`pkgs.tmux`](\n https://search.nixos.org/packages?show=tmux&sort=relevance&query=tmux\n )\n",
37 },
38 ...
39 }
40 ```
41
42 ## optionsDocBook
43
44 deprecated since 23.11 and will be removed in 24.05.
45
46 ## optionsAsciiDoc
47
48 Documentation rendered as AsciiDoc. This is useful for e.g. man pages.
49
50 > Note: NixOS itself uses this ouput to to build the configuration.nix man page"
51
52 ## optionsNix
53
54 All options as a Nix attribute set value, with the same schema as `optionsJSON`.
55
56 # Example
57
58 ## Example: NixOS configuration
59
60 ```nix
61 let
62 # Evaluate a NixOS configuration
63 eval = import (pkgs.path + "/nixos/lib/eval-config.nix") {
64 # Overriden explicitly here, this would include all modules from NixOS otherwise.
65 # See: docs of eval-config.nix for more details
66 baseModules = [];
67 modules = [
68 ./module.nix
69 ];
70 };
71 in
72 pkgs.nixosOptionsDoc {
73 inherit (eval) options;
74 }
75 ```
76
77 ## Example: non-NixOS modules
78
79 `nixosOptionsDoc` can also be used to build documentation for non-NixOS modules.
80
81 ```nix
82 let
83 eval = lib.evalModules {
84 modules = [
85 ./module.nix
86 ];
87 };
88 in
89 pkgs.nixosOptionsDoc {
90 inherit (eval) options;
91 }
92 ```
93*/
94{ pkgs
95, lib
96, options
97, transformOptions ? lib.id # function for additional transformations of the options
98, documentType ? "appendix" # TODO deprecate "appendix" in favor of "none"
99 # and/or rename function to moduleOptionDoc for clean slate
100
101 # If you include more than one option list into a document, you need to
102 # provide different ids.
103, variablelistId ? "configuration-variable-list"
104 # String to prefix to the option XML/HTML id attributes.
105, optionIdPrefix ? "opt-"
106, revision ? "" # Specify revision for the options
107# a set of options the docs we are generating will be merged into, as if by recursiveUpdate.
108# used to split the options doc build into a static part (nixos/modules) and a dynamic part
109# (non-nixos modules imported via configuration.nix, other module sources).
110, baseOptionsJSON ? null
111# instead of printing warnings for eg options with missing descriptions (which may be lost
112# by nix build unless -L is given), emit errors instead and fail the build
113, warningsAreErrors ? true
114# allow docbook option docs if `true`. only markdown documentation is allowed when set to
115# `false`, and a different renderer may be used with different bugs and performance
116# characteristics but (hopefully) indistinguishable output.
117# deprecated since 23.11.
118# TODO remove in a while.
119, allowDocBook ? false
120# TODO remove in a while (see https://github.com/NixOS/nixpkgs/issues/300735)
121, markdownByDefault ? true
122}:
123
124assert markdownByDefault && ! allowDocBook;
125
126let
127 rawOpts = lib.optionAttrSetToDocList options;
128 transformedOpts = map transformOptions rawOpts;
129 filteredOpts = lib.filter (opt: opt.visible && !opt.internal) transformedOpts;
130 optionsList = lib.flip map filteredOpts
131 (opt: opt
132 // lib.optionalAttrs (opt ? relatedPackages && opt.relatedPackages != []) { relatedPackages = genRelatedPackages opt.relatedPackages opt.name; }
133 );
134
135 # Generate DocBook documentation for a list of packages. This is
136 # what `relatedPackages` option of `mkOption` from
137 # ../../../lib/options.nix influences.
138 #
139 # Each element of `relatedPackages` can be either
140 # - a string: that will be interpreted as an attribute name from `pkgs` and turned into a link
141 # to search.nixos.org,
142 # - a list: that will be interpreted as an attribute path from `pkgs` and turned into a link
143 # to search.nixos.org,
144 # - an attrset: that can specify `name`, `path`, `comment`
145 # (either of `name`, `path` is required, the rest are optional).
146 #
147 # NOTE: No checks against `pkgs` are made to ensure that the referenced package actually exists.
148 # Such checks are not compatible with option docs caching.
149 genRelatedPackages = packages: optName:
150 let
151 unpack = p: if lib.isString p then { name = p; }
152 else if lib.isList p then { path = p; }
153 else p;
154 describe = args:
155 let
156 title = args.title or null;
157 name = args.name or (lib.concatStringsSep "." args.path);
158 in ''
159 - [${lib.optionalString (title != null) "${title} aka "}`pkgs.${name}`](
160 https://search.nixos.org/packages?show=${name}&sort=relevance&query=${name}
161 )${
162 lib.optionalString (args ? comment) "\n\n ${args.comment}"
163 }
164 '';
165 in lib.concatMapStrings (p: describe (unpack p)) packages;
166
167 optionsNix = builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList);
168
169in rec {
170 inherit optionsNix;
171
172 optionsAsciiDoc = pkgs.runCommand "options.adoc" {
173 nativeBuildInputs = [ pkgs.nixos-render-docs ];
174 } ''
175 nixos-render-docs -j $NIX_BUILD_CORES options asciidoc \
176 --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \
177 --revision ${lib.escapeShellArg revision} \
178 ${optionsJSON}/share/doc/nixos/options.json \
179 $out
180 '';
181
182 optionsCommonMark = pkgs.runCommand "options.md" {
183 nativeBuildInputs = [ pkgs.nixos-render-docs ];
184 } ''
185 nixos-render-docs -j $NIX_BUILD_CORES options commonmark \
186 --manpage-urls ${pkgs.path + "/doc/manpage-urls.json"} \
187 --revision ${lib.escapeShellArg revision} \
188 ${optionsJSON}/share/doc/nixos/options.json \
189 $out
190 '';
191
192 optionsJSON = pkgs.runCommand "options.json"
193 { meta.description = "List of NixOS options in JSON format";
194 nativeBuildInputs = [
195 pkgs.brotli
196 pkgs.python3
197 ];
198 options = builtins.toFile "options.json"
199 (builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix));
200 # merge with an empty set if baseOptionsJSON is null to run markdown
201 # processing on the input options
202 baseJSON =
203 if baseOptionsJSON == null
204 then builtins.toFile "base.json" "{}"
205 else baseOptionsJSON;
206 }
207 ''
208 # Export list of options in different format.
209 dst=$out/share/doc/nixos
210 mkdir -p $dst
211
212 TOUCH_IF_DB=$dst/.used-docbook \
213 python ${./mergeJSON.py} \
214 ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
215 $baseJSON $options \
216 > $dst/options.json
217
218 if grep /nixpkgs/nixos/modules $dst/options.json; then
219 echo "The manual appears to depend on the location of Nixpkgs, which is bad"
220 echo "since this prevents sharing via the NixOS channel. This is typically"
221 echo "caused by an option default that refers to a relative path (see above"
222 echo "for hints about the offending path)."
223 exit 1
224 fi
225
226 brotli -9 < $dst/options.json > $dst/options.json.br
227
228 mkdir -p $out/nix-support
229 echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products
230 echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products
231 '';
232
233 optionsDocBook = throw "optionsDocBook has been removed in 24.05";
234}