nixos/doc/manual/default.nix

   1 { pkgs
   2 , options
   3 , config
   4 , version
   5 , revision
   6 , extraSources ? []
   7 , baseOptionsJSON ? null
   8 , warningsAreErrors ? true
   9 , prefix ? ../../..
  10 }:
  11
  12 let
  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     cp -r ${../../../doc/release-notes} ./release-notes-nixpkgs
  83
  84     substituteInPlace ./manual.md \
  85       --replace-fail '@NIXOS_VERSION@' "${version}"
  86     substituteInPlace ./configuration/configuration.md \
  87       --replace-fail \
  88           '@MODULE_CHAPTERS@' \
  89           ${escapeShellArg (concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}
  90     substituteInPlace ./nixos-options.md \
  91       --replace-fail \
  92         '@NIXOS_OPTIONS_JSON@' \
  93         ${optionsDoc.optionsJSON}/${common.outputPath}/options.json
  94     substituteInPlace ./development/writing-nixos-tests.section.md \
  95       --replace-fail \
  96         '@NIXOS_TEST_OPTIONS_JSON@' \
  97         ${testOptionsDoc.optionsJSON}/${common.outputPath}/options.json
  98     sed -e '/@PYTHON_MACHINE_METHODS@/ {' -e 'r ${testDriverMachineDocstrings}/machine-methods.md' -e 'd' -e '}' \
  99       -i ./development/writing-nixos-tests.section.md
 100   '';
 101
 102 in rec {
 103   inherit (optionsDoc) optionsJSON optionsNix optionsDocBook;
 104
 105   # Generate the NixOS manual.
 106   manualHTML = runCommand "nixos-manual-html"
 107     { nativeBuildInputs = [ buildPackages.nixos-render-docs ];
 108       inputs = sourceFilesBySuffices ./. [ ".md" ];
 109       meta.description = "The NixOS manual in HTML format";
 110       allowedReferences = ["out"];
 111     }
 112     ''
 113       # Generate the HTML manual.
 114       dst=$out/${common.outputPath}
 115       mkdir -p $dst
 116
 117       cp ${../../../doc/style.css} $dst/style.css
 118       cp ${../../../doc/anchor.min.js} $dst/anchor.min.js
 119       cp ${../../../doc/anchor-use.js} $dst/anchor-use.js
 120
 121       cp -r ${pkgs.documentation-highlighter} $dst/highlightjs
 122
 123       ${prepareManualFromMD}
 124
 125       nixos-render-docs -j $NIX_BUILD_CORES manual html \
 126         --manpage-urls ${manpageUrls} \
 127         --redirects ${./redirects.json} \
 128         --revision ${escapeShellArg revision} \
 129         --generator "nixos-render-docs ${pkgs.lib.version}" \
 130         --stylesheet style.css \
 131         --stylesheet highlightjs/mono-blue.css \
 132         --script ./highlightjs/highlight.pack.js \
 133         --script ./highlightjs/loader.js \
 134         --script ./anchor.min.js \
 135         --script ./anchor-use.js \
 136         --toc-depth 1 \
 137         --chunk-toc-depth 1 \
 138         ./manual.md \
 139         $dst/${common.indexPath}
 140
 141       mkdir -p $out/nix-support
 142       echo "nix-build out $out" >> $out/nix-support/hydra-build-products
 143       echo "doc manual $dst" >> $out/nix-support/hydra-build-products
 144     ''; # */
 145
 146   # Alias for backward compatibility. TODO(@oxij): remove eventually.
 147   manual = manualHTML;
 148
 149   # Index page of the NixOS manual.
 150   manualHTMLIndex = "${manualHTML}/${common.outputPath}/${common.indexPath}";
 151
 152   manualEpub = runCommand "nixos-manual-epub"
 153     { nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin buildPackages.zip ];
 154       doc = ''
 155         <book xmlns="http://docbook.org/ns/docbook"
 156               xmlns:xlink="http://www.w3.org/1999/xlink"
 157               version="5.0"
 158               xml:id="book-nixos-manual">
 159           <info>
 160             <title>NixOS Manual</title>
 161             <subtitle>Version ${pkgs.lib.version}</subtitle>
 162           </info>
 163           <chapter>
 164             <title>Temporarily unavailable</title>
 165             <para>
 166               The NixOS manual is currently not available in EPUB format,
 167               please use the <link xlink:href="https://nixos.org/nixos/manual">HTML manual</link>
 168               instead.
 169             </para>
 170             <para>
 171               If you've used the EPUB manual in the past and it has been useful to you, please
 172               <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.
 173             </para>
 174           </chapter>
 175         </book>
 176       '';
 177       passAsFile = [ "doc" ];
 178     }
 179     ''
 180       # Generate the epub manual.
 181       dst=$out/${common.outputPath}
 182
 183       xsltproc \
 184         --param chapter.autolabel 0 \
 185         --nonet --xinclude --output $dst/epub/ \
 186         ${docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
 187         $docPath
 188
 189       echo "application/epub+zip" > mimetype
 190       manual="$dst/nixos-manual.epub"
 191       zip -0Xq "$manual" mimetype
 192       cd $dst/epub && zip -Xr9D "$manual" *
 193
 194       rm -rf $dst/epub
 195
 196       mkdir -p $out/nix-support
 197       echo "doc-epub manual $manual" >> $out/nix-support/hydra-build-products
 198     '';
 199
 200
 201   # Generate the `man configuration.nix` package
 202   nixos-configuration-reference-manpage = runCommand "nixos-configuration-reference-manpage"
 203     { nativeBuildInputs = [
 204         buildPackages.installShellFiles
 205         buildPackages.nixos-render-docs
 206       ];
 207       allowedReferences = ["out"];
 208     }
 209     ''
 210       # Generate manpages.
 211       mkdir -p $out/share/man/man5
 212       nixos-render-docs -j $NIX_BUILD_CORES options manpage \
 213         --revision ${escapeShellArg revision} \
 214         ${optionsJSON}/${common.outputPath}/options.json \
 215         $out/share/man/man5/configuration.nix.5
 216     '';
 217
 218 }