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