doc/doc-support/lib-function-docs.nix

   1 # Generates the documentation for library functions via nixdoc.
   2 # To build this derivation, run `nix-build -A nixpkgs-manual.lib-docs`
   3 {
   4   lib,
   5   stdenvNoCC,
   6   nixdoc,
   7   nix,
   8   nixpkgs ? { },
   9   libsets ? [
  10     {
  11       name = "asserts";
  12       description = "assertion functions";
  13     }
  14     {
  15       name = "attrsets";
  16       description = "attribute set functions";
  17     }
  18     {
  19       name = "strings";
  20       description = "string manipulation functions";
  21     }
  22     {
  23       name = "versions";
  24       description = "version string functions";
  25     }
  26     {
  27       name = "trivial";
  28       description = "miscellaneous functions";
  29     }
  30     {
  31       name = "fixedPoints";
  32       baseName = "fixed-points";
  33       description = "explicit recursion functions";
  34     }
  35     {
  36       name = "lists";
  37       description = "list manipulation functions";
  38     }
  39     {
  40       name = "debug";
  41       description = "debugging functions";
  42     }
  43     {
  44       name = "options";
  45       description = "NixOS / nixpkgs option handling";
  46     }
  47     {
  48       name = "path";
  49       description = "path functions";
  50     }
  51     {
  52       name = "filesystem";
  53       description = "filesystem functions";
  54     }
  55     {
  56       name = "fileset";
  57       description = "file set functions";
  58     }
  59     {
  60       name = "sources";
  61       description = "source filtering functions";
  62     }
  63     {
  64       name = "cli";
  65       description = "command-line serialization functions";
  66     }
  67     {
  68       name = "generators";
  69       description = "functions that create file formats from nix data structures";
  70     }
  71     {
  72       name = "gvariant";
  73       description = "GVariant formatted string serialization functions";
  74     }
  75     {
  76       name = "customisation";
  77       description = "Functions to customise (derivation-related) functions, derivatons, or attribute sets";
  78     }
  79     {
  80       name = "meta";
  81       description = "functions for derivation metadata";
  82     }
  83     {
  84       name = "derivations";
  85       description = "miscellaneous derivation-specific functions";
  86     }
  87   ],
  88 }:
  89
  90 stdenvNoCC.mkDerivation {
  91   name = "nixpkgs-lib-docs";
  92
  93   src = lib.fileset.toSource {
  94     root = ../..;
  95     fileset = ../../lib;
  96   };
  97
  98   buildInputs = [
  99     nixdoc
 100     nix
 101   ];
 102
 103   installPhase = ''
 104     export NIX_STATE_DIR=$(mktemp -d)
 105     nix-instantiate --eval --strict --json ${./lib-function-locations.nix} \
 106       --arg nixpkgsPath "./." \
 107       --argstr revision ${nixpkgs.rev or "master"} \
 108       --argstr libsetsJSON ${lib.escapeShellArg (builtins.toJSON libsets)} \
 109       --store $(mktemp -d) \
 110       > locations.json
 111
 112     function docgen {
 113       name=$1
 114       baseName=$2
 115       description=$3
 116       # TODO: wrap lib.$name in <literal>, make nixdoc not escape it
 117       if [[ -e "lib/$baseName.nix" ]]; then
 118         nixdoc -c "$name" -d "lib.$name: $description" -l locations.json -f "lib/$baseName.nix" > "$out/$name.md"
 119       else
 120         nixdoc -c "$name" -d "lib.$name: $description" -l locations.json -f "lib/$baseName/default.nix" > "$out/$name.md"
 121       fi
 122       echo "$out/$name.md" >> "$out/index.md"
 123     }
 124
 125     mkdir -p "$out"
 126
 127     cat > "$out/index.md" << 'EOF'
 128     ```{=include=} sections auto-id-prefix=auto-generated
 129     EOF
 130
 131     ${lib.concatMapStrings (
 132       {
 133         name,
 134         baseName ? name,
 135         description,
 136       }:
 137       ''
 138         docgen ${name} ${baseName} ${lib.escapeShellArg description}
 139       ''
 140     ) libsets}
 141
 142     echo '```' >> "$out/index.md"
 143   '';
 144 }