git.iko.soy/typeable/nixpkgs
on master help sign in
Extract NixOS options documentation generation to a function

Motivation is to support other repositories containing nixos modules that would like to generate options documentation: - nix-darwin - private repos - arion - ??

commit5cfd034af0afe55e4d25748ec986c71b3bfbe3dd authorDomen Kožar <domen@dev.si> dateThu 8 Aug 2019, 12:59 (7 years ago) parent9175a20
5 files changed+138−97
nixos/doc/manual/default.nix+9−97 nixos/lib/make-options-doc/default.nix+125 nixos/doc/manual/options-to-docbook.xsl → nixos/lib/make-options-doc/options-to-docbook.xsl nixos/doc/manual/postprocess-option-descriptions.xsl → nixos/lib/make-options-doc/postprocess-option-descriptions.xsl pkgs/top-level/all-packages.nix+4
nixos/doc/manual/default.nix+9−97
@@ -5,55 +5,6 @@ with pkgs;
55let
66 lib = pkgs.lib;
77
8− # Remove invisible and internal options.
9− optionsListVisible = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options);
10−
11− # Replace functions by the string <function>
12− substFunction = x:
13− if builtins.isAttrs x then lib.mapAttrs (name: substFunction) x
14− else if builtins.isList x then map substFunction x
15− else if lib.isFunction x then "<function>"
16− else x;
17−
18− # Generate DocBook documentation for a list of packages. This is
19− # what `relatedPackages` option of `mkOption` from
20− # ../../../lib/options.nix influences.
21− #
22− # Each element of `relatedPackages` can be either
23− # - a string: that will be interpreted as an attribute name from `pkgs`,
24− # - a list: that will be interpreted as an attribute path from `pkgs`,
25− # - an attrset: that can specify `name`, `path`, `package`, `comment`
26− # (either of `name`, `path` is required, the rest are optional).
27− genRelatedPackages = packages:
28− let
29− unpack = p: if lib.isString p then { name = p; }
30− else if lib.isList p then { path = p; }
31− else p;
32− describe = args:
33− let
34− title = args.title or null;
35− name = args.name or (lib.concatStringsSep "." args.path);
36− path = args.path or [ args.name ];
37− package = args.package or (lib.attrByPath path (throw "Invalid package attribute path `${toString path}'") pkgs);
38− in "<listitem>"
39− + "<para><literal>${lib.optionalString (title != null) "${title} aka "}pkgs.${name} (${package.meta.name})</literal>"
40− + lib.optionalString (!package.meta.available) " <emphasis>[UNAVAILABLE]</emphasis>"
41− + ": ${package.meta.description or "???"}.</para>"
42− + lib.optionalString (args ? comment) "\n<para>${args.comment}</para>"
43− # Lots of `longDescription's break DocBook, so we just wrap them into <programlisting>
44− + lib.optionalString (package.meta ? longDescription) "\n<programlisting>${package.meta.longDescription}</programlisting>"
45− + "</listitem>";
46− in "<itemizedlist>${lib.concatStringsSep "\n" (map (p: describe (unpack p)) packages)}</itemizedlist>";
47−
48− optionsListDesc = lib.flip map optionsListVisible (opt: opt // {
49− # Clean up declaration sites to not refer to the NixOS source tree.
50− declarations = map stripAnyPrefixes opt.declarations;
51− }
52− // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; }
53− // lib.optionalAttrs (opt ? default) { default = substFunction opt.default; }
54− // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; }
55− // lib.optionalAttrs (opt ? relatedPackages && opt.relatedPackages != []) { relatedPackages = genRelatedPackages opt.relatedPackages; });
56−
578 # We need to strip references to /nix/store/* from options,
589 # including any `extraSources` if some modules came from elsewhere,
5910 # or else the build will fail.
@@ -63,37 +14,13 @@ let
6314 prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources);
6415 stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip;
6516
66− # Custom "less" that pushes up all the things ending in ".enable*"
67− # and ".package*"
68− optionLess = a: b:
69− let
70− ise = lib.hasPrefix "enable";
71− isp = lib.hasPrefix "package";
72− cmp = lib.splitByAndCompare ise lib.compare
73− (lib.splitByAndCompare isp lib.compare lib.compare);
74− in lib.compareLists cmp a.loc b.loc < 0;
75−
76− # Customly sort option list for the man page.
77− optionsList = lib.sort optionLess optionsListDesc;
78−
79− # Convert the list of options into an XML file.
80− optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList);
81−
82− optionsDocBook = runCommand "options-db.xml" {} ''
83− optionsXML=${optionsXML}
84− if grep /nixpkgs/nixos/modules $optionsXML; then
85− echo "The manual appears to depend on the location of Nixpkgs, which is bad"
86− echo "since this prevents sharing via the NixOS channel. This is typically"
87− echo "caused by an option default that refers to a relative path (see above"
88− echo "for hints about the offending path)."
89− exit 1
90− fi
91− ${buildPackages.libxslt.bin}/bin/xsltproc \
92− --stringparam revision '${revision}' \
93− -o intermediate.xml ${./options-to-docbook.xsl} $optionsXML
94− ${buildPackages.libxslt.bin}/bin/xsltproc \
95− -o "$out" ${./postprocess-option-descriptions.xsl} intermediate.xml
96− '';
17+ optionsDoc = buildPackages.nixosOptionsDoc {
18+ inherit options revision;
19+ transformOptions = opt: opt // {
20+ # Clean up declaration sites to not refer to the NixOS source tree.
21+ declarations = map stripAnyPrefixes opt.declarations;
22+ };
23+ };
9724
9825 sources = lib.sourceFilesBySuffices ./. [".xml"];
9926
@@ -108,7 +35,7 @@ let
10835 generatedSources = runCommand "generated-docbook" {} ''
10936 mkdir $out
11037 ln -s ${modulesDoc} $out/modules.xml
111− ln -s ${optionsDocBook} $out/options-db.xml
38+ ln -s ${optionsDoc.optionsDocBook} $out/options-db.xml
11239 printf "%s" "${version}" > $out/version
11340 '';
11441
@@ -234,22 +161,7 @@ let
234161in rec {
235162 inherit generatedSources;
236163
237− # The NixOS options in JSON format.
238− optionsJSON = runCommand "options-json"
239− { meta.description = "List of NixOS options in JSON format";
240− }
241− ''
242− # Export list of options in different format.
243− dst=$out/share/doc/nixos
244− mkdir -p $dst
245−
246− cp ${builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON
247− (builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList))))
248− } $dst/options.json
249−
250− mkdir -p $out/nix-support
251− echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products
252− ''; # */
164+ inherit (optionsDoc) optionsJSON optionsXML optionsDocBook;
253165
254166 # Generate the NixOS manual.
255167 manualHTML = runCommand "nixos-manual-html"
nixos/lib/make-options-doc/default.nixnew file+125
@@ -0,0 +1,125 @@
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+
26+let
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; }
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:
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}'") 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+in rec {
92+ # The NixOS options in JSON format.
93+ optionsJSON = pkgs.runCommand "options.json"
94+ { meta.description = "List of NixOS options in JSON format";
95+ }
96+ ''
97+ # Export list of options in different format.
98+ dst=$out/share/doc/nixos
99+ mkdir -p $dst
100+
101+ cp ${builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON
102+ (builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList))))
103+ } $dst/options.json
104+
105+ mkdir -p $out/nix-support
106+ echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products
107+ ''; # */
108+
109+ optionsDocBook = pkgs.runCommand "options-docbook.xml" {} ''
110+ optionsXML=${optionsXML}
111+ if grep /nixpkgs/nixos/modules $optionsXML; then
112+ echo "The manual appears to depend on the location of Nixpkgs, which is bad"
113+ echo "since this prevents sharing via the NixOS channel. This is typically"
114+ echo "caused by an option default that refers to a relative path (see above"
115+ echo "for hints about the offending path)."
116+ exit 1
117+ fi
118+
119+ ${pkgs.libxslt.bin}/bin/xsltproc \
120+ --stringparam revision '${revision}' \
121+ -o intermediate.xml ${./options-to-docbook.xsl} $optionsXML
122+ ${pkgs.libxslt.bin}/bin/xsltproc \
123+ -o "$out" ${./postprocess-option-descriptions.xsl} intermediate.xml
124+ '';
125+}
nixos/doc/manual/options-to-docbook.xsl → nixos/lib/make-options-doc/options-to-docbook.xslrenamed

The content is the same.

nixos/doc/manual/postprocess-option-descriptions.xsl → nixos/lib/make-options-doc/postprocess-option-descriptions.xslrenamed

The content is the same.

pkgs/top-level/all-packages.nix+4
@@ -23876,6 +23876,10 @@ in
2387623876 in
2387723877 nixosTesting.makeTest calledTest;
2387823878
23879+ nixosOptionsDoc = attrs:
23880+ (import ../../nixos/lib/make-options-doc/default.nix)
23881+ ({ inherit pkgs lib; } // attrs);
23882+
2387923883 nixui = callPackage ../tools/package-management/nixui { node_webkit = nwjs_0_12; };
2388023884
2388123885 nixdoc = callPackage ../tools/nix/nixdoc {};