pyrox.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 = "fetchers";
53 description = "functions which can be reused across fetchers";
54 }
55 {
56 name = "filesystem";
57 description = "filesystem functions";
58 }
59 {
60 name = "fileset";
61 description = "file set functions";
62 }
63 {
64 name = "sources";
65 description = "source filtering functions";
66 }
67 {
68 name = "cli";
69 description = "command-line serialization functions";
70 }
71 {
72 name = "generators";
73 description = "functions that create file formats from nix data structures";
74 }
75 {
76 name = "gvariant";
77 description = "GVariant formatted string serialization functions";
78 }
79 {
80 name = "customisation";
81 description = "Functions to customise (derivation-related) functions, derivations, or attribute sets";
82 }
83 {
84 name = "meta";
85 description = "functions for derivation metadata";
86 }
87 {
88 name = "derivations";
89 description = "miscellaneous derivation-specific functions";
90 }
91 ],
92}:
93
94stdenvNoCC.mkDerivation {
95 name = "nixpkgs-lib-docs";
96
97 src = ../../lib;
98
99 nativeBuildInputs = [
100 nixdoc
101 nix
102 ];
103
104 installPhase = ''
105 runHook preInstall
106
107 cd ..
108
109 export NIX_STATE_DIR=$(mktemp -d)
110 nix-instantiate --eval --strict --json ${./lib-function-locations.nix} \
111 --arg nixpkgsPath "./." \
112 --argstr revision ${nixpkgs.rev or "master"} \
113 --argstr libsetsJSON ${lib.escapeShellArg (builtins.toJSON libsets)} \
114 --store $(mktemp -d) \
115 > locations.json
116
117 function docgen {
118 name=$1
119 baseName=$2
120 description=$3
121 # TODO: wrap lib.$name in <literal>, make nixdoc not escape it
122 if [[ -e "lib/$baseName.nix" ]]; then
123 nixdoc -c "$name" -d "lib.$name: $description" -l locations.json -f "lib/$baseName.nix" > "$out/$name.md"
124 else
125 nixdoc -c "$name" -d "lib.$name: $description" -l locations.json -f "lib/$baseName/default.nix" > "$out/$name.md"
126 fi
127 echo "$out/$name.md" >> "$out/index.md"
128 }
129
130 mkdir -p "$out"
131
132 cat > "$out/index.md" << 'EOF'
133 ```{=include=} sections auto-id-prefix=auto-generated
134 EOF
135
136 ${lib.concatMapStrings (
137 {
138 name,
139 baseName ? name,
140 description,
141 }:
142 ''
143 docgen ${name} ${baseName} ${lib.escapeShellArg description}
144 ''
145 ) libsets}
146
147 echo '```' >> "$out/index.md"
148
149 runHook postInstall
150 '';
151}