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

   1 # Generates the documentation for library functions via nixdoc.
   2
   3 { pkgs, nixpkgs, libsets }:
   4
   5 with pkgs;
   6
   7 let
   8   locationsJSON = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };
   9 in
  10 stdenv.mkDerivation {
  11   name = "nixpkgs-lib-docs";
  12   src = ../../lib;
  13
  14   buildInputs = [ nixdoc ];
  15   installPhase = ''
  16     function docgen {
  17       name=$1
  18       baseName=$2
  19       description=$3
  20       # TODO: wrap lib.$name in <literal>, make nixdoc not escape it
  21       if [[ -e "../lib/$baseName.nix" ]]; then
  22         nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName.nix" > "$out/$name.md"
  23       else
  24         nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName/default.nix" > "$out/$name.md"
  25       fi
  26       echo "$out/$name.md" >> "$out/index.md"
  27     }
  28
  29     mkdir -p "$out"
  30
  31     cat > "$out/index.md" << 'EOF'
  32     ```{=include=} sections auto-id-prefix=auto-generated
  33     EOF
  34
  35     ${lib.concatMapStrings ({ name, baseName ? name, description }: ''
  36       docgen ${name} ${baseName} ${lib.escapeShellArg description}
  37     '') libsets}
  38
  39     echo '```' >> "$out/index.md"
  40   '';
  41 }