doc/default.nix

   1 { pkgs ? (import ./.. { }), nixpkgs ? { }}:
   2 let
   3   inherit (pkgs) lib;
   4   inherit (lib) hasPrefix removePrefix;
   5
   6   common = import ./common.nix;
   7
   8   lib-docs = import ./doc-support/lib-function-docs.nix {
   9     inherit pkgs nixpkgs;
  10     libsets = [
  11       { name = "asserts"; description = "assertion functions"; }
  12       { name = "attrsets"; description = "attribute set functions"; }
  13       { name = "strings"; description = "string manipulation functions"; }
  14       { name = "versions"; description = "version string functions"; }
  15       { name = "trivial"; description = "miscellaneous functions"; }
  16       { name = "fixedPoints"; baseName = "fixed-points"; description = "explicit recursion functions"; }
  17       { name = "lists"; description = "list manipulation functions"; }
  18       { name = "debug"; description = "debugging functions"; }
  19       { name = "options"; description = "NixOS / nixpkgs option handling"; }
  20       { name = "path"; description = "path functions"; }
  21       { name = "filesystem"; description = "filesystem functions"; }
  22       { name = "fileset"; description = "file set functions"; }
  23       { name = "sources"; description = "source filtering functions"; }
  24       { name = "cli"; description = "command-line serialization functions"; }
  25       { name = "gvariant"; description = "GVariant formatted string serialization functions"; }
  26       { name = "customisation"; description = "Functions to customise (derivation-related) functions, derivatons, or attribute sets"; }
  27       { name = "meta"; description = "functions for derivation metadata"; }
  28       { name = "derivations"; description = "miscellaneous derivation-specific functions"; }
  29     ];
  30   };
  31
  32   epub = pkgs.runCommand "manual.epub" {
  33     nativeBuildInputs = with pkgs; [ libxslt zip ];
  34
  35     epub = ''
  36       <book xmlns="http://docbook.org/ns/docbook"
  37             xmlns:xlink="http://www.w3.org/1999/xlink"
  38             version="5.0"
  39             xml:id="nixpkgs-manual">
  40         <info>
  41           <title>Nixpkgs Manual</title>
  42           <subtitle>Version ${pkgs.lib.version}</subtitle>
  43         </info>
  44         <chapter>
  45           <title>Temporarily unavailable</title>
  46           <para>
  47             The Nixpkgs manual is currently not available in EPUB format,
  48             please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link>
  49             instead.
  50           </para>
  51           <para>
  52             If you've used the EPUB manual in the past and it has been useful to you, please
  53             <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.
  54           </para>
  55         </chapter>
  56       </book>
  57     '';
  58
  59     passAsFile = [ "epub" ];
  60   } ''
  61     mkdir scratch
  62     xsltproc \
  63       --param chapter.autolabel 0 \
  64       --nonet \
  65       --output scratch/ \
  66       ${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
  67       $epubPath
  68
  69     echo "application/epub+zip" > mimetype
  70     zip -0Xq "$out" mimetype
  71     cd scratch && zip -Xr9D "$out" *
  72   '';
  73
  74   # NB: This file describes the Nixpkgs manual, which happens to use module
  75   #     docs infra originally developed for NixOS.
  76   optionsDoc = pkgs.nixosOptionsDoc {
  77     inherit (pkgs.lib.evalModules {
  78       modules = [ ../pkgs/top-level/config.nix ];
  79       class = "nixpkgsConfig";
  80     }) options;
  81     documentType = "none";
  82     transformOptions = opt:
  83       opt // {
  84         declarations =
  85           map
  86             (decl:
  87               if hasPrefix (toString ../..) (toString decl)
  88               then
  89                 let subpath = removePrefix "/" (removePrefix (toString ../.) (toString decl));
  90                 in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
  91               else decl)
  92             opt.declarations;
  93         };
  94   };
  95 in pkgs.stdenv.mkDerivation {
  96   name = "nixpkgs-manual";
  97
  98   nativeBuildInputs = with pkgs; [
  99     nixos-render-docs
 100   ];
 101
 102   src = ./.;
 103
 104   postPatch = ''
 105     ln -s ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./config-options.json
 106   '';
 107
 108   buildPhase = ''
 109     cat \
 110       ./functions/library.md.in \
 111       ${lib-docs}/index.md \
 112       > ./functions/library.md
 113     substitute ./manual.md.in ./manual.md \
 114       --replace-fail '@MANUAL_VERSION@' '${pkgs.lib.version}'
 115
 116     mkdir -p out/media
 117
 118     mkdir -p out/highlightjs
 119     cp -t out/highlightjs \
 120       ${pkgs.documentation-highlighter}/highlight.pack.js \
 121       ${pkgs.documentation-highlighter}/LICENSE \
 122       ${pkgs.documentation-highlighter}/mono-blue.css \
 123       ${pkgs.documentation-highlighter}/loader.js
 124
 125     cp -t out ./style.css ./anchor.min.js ./anchor-use.js
 126
 127     nixos-render-docs manual html \
 128       --manpage-urls ./manpage-urls.json \
 129       --revision ${pkgs.lib.trivial.revisionWithDefault (pkgs.rev or "master")} \
 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       --section-toc-depth 1 \
 138       manual.md \
 139       out/index.html
 140   '';
 141
 142   installPhase = ''
 143     dest="$out/${common.outputPath}"
 144     mkdir -p "$(dirname "$dest")"
 145     mv out "$dest"
 146     mv "$dest/index.html" "$dest/${common.indexPath}"
 147
 148     cp ${epub} "$dest/nixpkgs-manual.epub"
 149
 150     mkdir -p $out/nix-support/
 151     echo "doc manual $dest ${common.indexPath}" >> $out/nix-support/hydra-build-products
 152     echo "doc manual $dest nixpkgs-manual.epub" >> $out/nix-support/hydra-build-products
 153   '';
 154
 155   passthru.tests.manpage-urls = with pkgs; testers.invalidateFetcherByDrvHash
 156     ({ name ? "manual_check-manpage-urls"
 157      , script
 158      , urlsFile
 159      }: runCommand name {
 160       nativeBuildInputs = [
 161         cacert
 162         (python3.withPackages (p: with p; [
 163           aiohttp
 164           rich
 165           structlog
 166         ]))
 167       ];
 168       outputHash = "sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=";  # Empty output
 169     } ''
 170       python3 ${script} ${urlsFile}
 171       touch $out
 172     '') {
 173       script = ./tests/manpage-urls.py;
 174       urlsFile = ./manpage-urls.json;
 175     };
 176 }