tjh.dev
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, derivations, 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
90stdenvNoCC.mkDerivation {
91 name = "nixpkgs-lib-docs";
92
93 src = lib.fileset.toSource {
94 root = ../..;
95 fileset = ../../lib;
96 };
97
98 nativeBuildInputs = [
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}