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