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     substituteInPlace ./manual.md \
  83       --replace '@NIXOS_VERSION@' "${version}"
  84     substituteInPlace ./configuration/configuration.md \
  85       --replace \
  86           '@MODULE_CHAPTERS@' \
  87           ${escapeShellArg (concatMapStringsSep "\n" (p: "${p.value}") config.meta.doc)}
  88     substituteInPlace ./nixos-options.md \
  89       --replace \
  90         '@NIXOS_OPTIONS_JSON@' \
  91         ${optionsDoc.optionsJSON}/${common.outputPath}/options.json
  92     substituteInPlace ./development/writing-nixos-tests.section.md \
  93       --replace \
  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
 100 in 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 }