pyrox.dev
1{ pkgs
2, options
3, config
4, version
5, revision
6, extraSources ? []
7, baseOptionsJSON ? null
8, warningsAreErrors ? true
9, prefix ? ../../..
10}:
11
12let
13 inherit (pkgs) buildPackages runCommand docbook_xsl_ns;
14
15 inherit (pkgs.lib)
16 hasPrefix
17 removePrefix
18 flip
19 foldr
20 types
21 mkOption
22 escapeShellArg
23 concatMapStringsSep
24 sourceFilesBySuffices
25 ;
26
27 common = import ./common.nix;
28
29 manpageUrls = pkgs.path + "/doc/manpage-urls.json";
30
31 # We need to strip references to /nix/store/* from options,
32 # including any `extraSources` if some modules came from elsewhere,
33 # or else the build will fail.
34 #
35 # E.g. if some `options` came from modules in ${pkgs.customModules}/nix,
36 # you'd need to include `extraSources = [ pkgs.customModules ]`
37 prefixesToStrip = map (p: "${toString p}/") ([ prefix ] ++ extraSources);
38 stripAnyPrefixes = flip (foldr removePrefix) prefixesToStrip;
39
40 optionsDoc = buildPackages.nixosOptionsDoc {
41 inherit options revision baseOptionsJSON warningsAreErrors;
42 transformOptions = opt: opt // {
43 # Clean up declaration sites to not refer to the NixOS source tree.
44 declarations = map stripAnyPrefixes opt.declarations;
45 };
46 };
47
48 nixos-lib = import ../../lib { };
49
50 testOptionsDoc = let
51 eval = nixos-lib.evalTest {
52 # Avoid evaluating a NixOS config prototype.
53 config.node.type = types.deferredModule;
54 options._module.args = mkOption { internal = true; };
55 };
56 in buildPackages.nixosOptionsDoc {
57 inherit (eval) options;
58 inherit revision;
59 transformOptions = opt: opt // {
60 # Clean up declaration sites to not refer to the NixOS source tree.
61 declarations =
62 map
63 (decl:
64 if hasPrefix (toString ../../..) (toString decl)
65 then
66 let subpath = removePrefix "/" (removePrefix (toString ../../..) (toString decl));
67 in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
68 else decl)
69 opt.declarations;
70 };
71 documentType = "none";
72 variablelistId = "test-options-list";
73 optionIdPrefix = "test-opt-";
74 };
75
76 testDriverMachineDocstrings = pkgs.callPackage
77 ../../../nixos/lib/test-driver/nixos-test-driver-docstrings.nix {};
78
79 prepareManualFromMD = ''
80 cp -r --no-preserve=all $inputs/* .
81
82 substituteInPlace ./manual.md \
83 --replace-fail '@NIXOS_VERSION@' "${version}"
84 substituteInPlace ./configuration/configuration.md \
85 --replace-fail \
86 '@MODULE_CHAPTERS@' \
87 ${escapeShellArg (concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}
88 substituteInPlace ./nixos-options.md \
89 --replace-fail \
90 '@NIXOS_OPTIONS_JSON@' \
91 ${optionsDoc.optionsJSON}/${common.outputPath}/options.json
92 substituteInPlace ./development/writing-nixos-tests.section.md \
93 --replace-fail \
94 '@NIXOS_TEST_OPTIONS_JSON@' \
95 ${testOptionsDoc.optionsJSON}/${common.outputPath}/options.json
96 sed -e '/@PYTHON_MACHINE_METHODS@/ {' -e 'r ${testDriverMachineDocstrings}/machine-methods.md' -e 'd' -e '}' \
97 -i ./development/writing-nixos-tests.section.md
98 '';
99
100in rec {
101 inherit (optionsDoc) optionsJSON optionsNix optionsDocBook;
102
103 # Generate the NixOS manual.
104 manualHTML = runCommand "nixos-manual-html"
105 { nativeBuildInputs = [ buildPackages.nixos-render-docs ];
106 inputs = sourceFilesBySuffices ./. [ ".md" ];
107 meta.description = "The NixOS manual in HTML format";
108 allowedReferences = ["out"];
109 }
110 ''
111 # Generate the HTML manual.
112 dst=$out/${common.outputPath}
113 mkdir -p $dst
114
115 cp ${../../../doc/style.css} $dst/style.css
116 cp ${../../../doc/anchor.min.js} $dst/anchor.min.js
117 cp ${../../../doc/anchor-use.js} $dst/anchor-use.js
118
119 cp -r ${pkgs.documentation-highlighter} $dst/highlightjs
120
121 ${prepareManualFromMD}
122
123 nixos-render-docs -j $NIX_BUILD_CORES manual html \
124 --manpage-urls ${manpageUrls} \
125 --revision ${escapeShellArg revision} \
126 --generator "nixos-render-docs ${pkgs.lib.version}" \
127 --stylesheet style.css \
128 --stylesheet highlightjs/mono-blue.css \
129 --script ./highlightjs/highlight.pack.js \
130 --script ./highlightjs/loader.js \
131 --script ./anchor.min.js \
132 --script ./anchor-use.js \
133 --toc-depth 1 \
134 --chunk-toc-depth 1 \
135 ./manual.md \
136 $dst/${common.indexPath}
137
138 mkdir -p $out/nix-support
139 echo "nix-build out $out" >> $out/nix-support/hydra-build-products
140 echo "doc manual $dst" >> $out/nix-support/hydra-build-products
141 ''; # */
142
143 # Alias for backward compatibility. TODO(@oxij): remove eventually.
144 manual = manualHTML;
145
146 # Index page of the NixOS manual.
147 manualHTMLIndex = "${manualHTML}/${common.outputPath}/${common.indexPath}";
148
149 manualEpub = runCommand "nixos-manual-epub"
150 { nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin buildPackages.zip ];
151 doc = ''
152 <book xmlns="http://docbook.org/ns/docbook"
153 xmlns:xlink="http://www.w3.org/1999/xlink"
154 version="5.0"
155 xml:id="book-nixos-manual">
156 <info>
157 <title>NixOS Manual</title>
158 <subtitle>Version ${pkgs.lib.version}</subtitle>
159 </info>
160 <chapter>
161 <title>Temporarily unavailable</title>
162 <para>
163 The NixOS manual is currently not available in EPUB format,
164 please use the <link xlink:href="https://nixos.org/nixos/manual">HTML manual</link>
165 instead.
166 </para>
167 <para>
168 If you've used the EPUB manual in the past and it has been useful to you, please
169 <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.
170 </para>
171 </chapter>
172 </book>
173 '';
174 passAsFile = [ "doc" ];
175 }
176 ''
177 # Generate the epub manual.
178 dst=$out/${common.outputPath}
179
180 xsltproc \
181 --param chapter.autolabel 0 \
182 --nonet --xinclude --output $dst/epub/ \
183 ${docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
184 $docPath
185
186 echo "application/epub+zip" > mimetype
187 manual="$dst/nixos-manual.epub"
188 zip -0Xq "$manual" mimetype
189 cd $dst/epub && zip -Xr9D "$manual" *
190
191 rm -rf $dst/epub
192
193 mkdir -p $out/nix-support
194 echo "doc-epub manual $manual" >> $out/nix-support/hydra-build-products
195 '';
196
197
198 # Generate the `man configuration.nix` package
199 nixos-configuration-reference-manpage = runCommand "nixos-configuration-reference-manpage"
200 { nativeBuildInputs = [
201 buildPackages.installShellFiles
202 buildPackages.nixos-render-docs
203 ];
204 allowedReferences = ["out"];
205 }
206 ''
207 # Generate manpages.
208 mkdir -p $out/share/man/man5
209 nixos-render-docs -j $NIX_BUILD_CORES options manpage \
210 --revision ${escapeShellArg revision} \
211 ${optionsJSON}/${common.outputPath}/options.json \
212 $out/share/man/man5/configuration.nix.5
213 '';
214
215}