pyrox.dev
1/* Generate JSON, XML and DocBook documentation for given NixOS options.
2
3 Minimal example:
4
5 { pkgs, }:
6
7 let
8 eval = import (pkgs.path + "/nixos/lib/eval-config.nix") {
9 baseModules = [
10 ../module.nix
11 ];
12 modules = [];
13 };
14 in pkgs.nixosOptionsDoc {
15 options = eval.options;
16 }
17
18*/
19{ pkgs
20, lib
21, options
22, transformOptions ? lib.id # function for additional tranformations of the options
23, revision ? "" # Specify revision for the options
24}:
25
26let
27 # Replace functions by the string <function>
28 substFunction = x:
29 if builtins.isAttrs x then lib.mapAttrs (name: substFunction) x
30 else if builtins.isList x then map substFunction x
31 else if lib.isFunction x then "<function>"
32 else x;
33
34 optionsListDesc = lib.flip map optionsListVisible
35 (opt: transformOptions opt
36 // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; }
37 // lib.optionalAttrs (opt ? default) { default = substFunction opt.default; }
38 // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; }
39 // lib.optionalAttrs (opt ? relatedPackages && opt.relatedPackages != []) { relatedPackages = genRelatedPackages opt.relatedPackages opt.name; }
40 );
41
42 # Generate DocBook documentation for a list of packages. This is
43 # what `relatedPackages` option of `mkOption` from
44 # ../../../lib/options.nix influences.
45 #
46 # Each element of `relatedPackages` can be either
47 # - a string: that will be interpreted as an attribute name from `pkgs`,
48 # - a list: that will be interpreted as an attribute path from `pkgs`,
49 # - an attrset: that can specify `name`, `path`, `package`, `comment`
50 # (either of `name`, `path` is required, the rest are optional).
51 genRelatedPackages = packages: optName:
52 let
53 unpack = p: if lib.isString p then { name = p; }
54 else if lib.isList p then { path = p; }
55 else p;
56 describe = args:
57 let
58 title = args.title or null;
59 name = args.name or (lib.concatStringsSep "." args.path);
60 path = args.path or [ args.name ];
61 package = args.package or (lib.attrByPath path (throw "Invalid package attribute path `${toString path}' found while evaluating `relatedPackages' of option `${optName}'") pkgs);
62 in "<listitem>"
63 + "<para><literal>${lib.optionalString (title != null) "${title} aka "}pkgs.${name} (${package.meta.name})</literal>"
64 + lib.optionalString (!package.meta.available) " <emphasis>[UNAVAILABLE]</emphasis>"
65 + ": ${package.meta.description or "???"}.</para>"
66 + lib.optionalString (args ? comment) "\n<para>${args.comment}</para>"
67 # Lots of `longDescription's break DocBook, so we just wrap them into <programlisting>
68 + lib.optionalString (package.meta ? longDescription) "\n<programlisting>${package.meta.longDescription}</programlisting>"
69 + "</listitem>";
70 in "<itemizedlist>${lib.concatStringsSep "\n" (map (p: describe (unpack p)) packages)}</itemizedlist>";
71
72 # Custom "less" that pushes up all the things ending in ".enable*"
73 # and ".package*"
74 optionLess = a: b:
75 let
76 ise = lib.hasPrefix "enable";
77 isp = lib.hasPrefix "package";
78 cmp = lib.splitByAndCompare ise lib.compare
79 (lib.splitByAndCompare isp lib.compare lib.compare);
80 in lib.compareLists cmp a.loc b.loc < 0;
81
82 # Remove invisible and internal options.
83 optionsListVisible = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options);
84
85 # Customly sort option list for the man page.
86 optionsList = lib.sort optionLess optionsListDesc;
87
88 # Convert the list of options into an XML file.
89 optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList);
90
91 optionsNix = builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList);
92
93 # TODO: declarations: link to github
94 singleAsciiDoc = name: value: ''
95 == ${name}
96
97 ${value.description}
98
99 [discrete]
100 === details
101
102 Type:: ${value.type}
103 ${ if lib.hasAttr "default" value
104 then ''
105 Default::
106 +
107 ----
108 ${builtins.toJSON value.default}
109 ----
110 ''
111 else "No Default:: {blank}"
112 }
113 ${ if value.readOnly
114 then "Read Only:: {blank}"
115 else ""
116 }
117 ${ if lib.hasAttr "example" value
118 then ''
119 Example::
120 +
121 ----
122 ${builtins.toJSON value.example}
123 ----
124 ''
125 else "No Example:: {blank}"
126 }
127 '';
128
129 singleMDDoc = name: value: ''
130 ## ${lib.escape [ "<" ">" ] name}
131 ${value.description}
132
133 ${lib.optionalString (value ? type) ''
134 *_Type_*:
135 ${value.type}
136 ''}
137
138 ${lib.optionalString (value ? default) ''
139 *_Default_*
140 ```
141 ${builtins.toJSON value.default}
142 ```
143 ''}
144
145 ${lib.optionalString (value ? example) ''
146 *_Example_*
147 ```
148 ${builtins.toJSON value.example}
149 ```
150 ''}
151 '';
152
153in {
154 inherit optionsNix;
155
156 optionsAsciiDoc = lib.concatStringsSep "\n" (lib.mapAttrsToList singleAsciiDoc optionsNix);
157
158 optionsMDDoc = lib.concatStringsSep "\n" (lib.mapAttrsToList singleMDDoc optionsNix);
159
160 optionsJSON = pkgs.runCommand "options.json"
161 { meta.description = "List of NixOS options in JSON format";
162 buildInputs = [ pkgs.brotli ];
163 }
164 ''
165 # Export list of options in different format.
166 dst=$out/share/doc/nixos
167 mkdir -p $dst
168
169 cp ${builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix))} $dst/options.json
170
171 brotli -9 < $dst/options.json > $dst/options.json.br
172
173 mkdir -p $out/nix-support
174 echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products
175 echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products
176 ''; # */
177
178 optionsDocBook = pkgs.runCommand "options-docbook.xml" {} ''
179 optionsXML=${optionsXML}
180 if grep /nixpkgs/nixos/modules $optionsXML; then
181 echo "The manual appears to depend on the location of Nixpkgs, which is bad"
182 echo "since this prevents sharing via the NixOS channel. This is typically"
183 echo "caused by an option default that refers to a relative path (see above"
184 echo "for hints about the offending path)."
185 exit 1
186 fi
187
188 ${pkgs.libxslt.bin}/bin/xsltproc \
189 --stringparam revision '${revision}' \
190 -o intermediate.xml ${./options-to-docbook.xsl} $optionsXML
191 ${pkgs.libxslt.bin}/bin/xsltproc \
192 -o "$out" ${./postprocess-option-descriptions.xsl} intermediate.xml
193 '';
194}