Skip to content

Commit 4414d8a

Browse files
MattSturgeonMattSturgeon
committed
docs/modules: init
Modules to represent pages in the docs
1 parent 9faa339 commit 4414d8a

File tree

6 files changed

+307
-185
lines changed

6 files changed

+307
-185
lines changed

‎docs/lib/default.nix‎

Lines changed: 129 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -6,173 +6,147 @@
66
writers,
77
nixdoc,
88
nixvim,
9-
pageSpecs ? import ./pages.nix,
9+
pageSpecs ? ./pages.nix,
1010
}:
1111

1212
let
13-
# Some pages are just menu entries, others have an actual markdown page that
14-
# needs rendering.
15-
shouldRenderPage = page: page ? file || page ? markdown;
16-
17-
# Normalise a page node, recursively normalise its children
18-
elaboratePage =
19-
loc:
20-
{
21-
title ? "",
22-
markdown ? null,
23-
file ? null,
24-
pages ? { },
25-
}@page:
26-
{
27-
name = lib.attrsets.showAttrPath loc;
28-
loc = lib.throwIfNot (
29-
builtins.head loc == "lib"
30-
) "All pages must be within `lib`, unexpected root `${builtins.head loc}`" (builtins.tail loc);
31-
}
32-
// lib.optionalAttrs (shouldRenderPage page) {
33-
inherit
34-
file
35-
title
36-
;
37-
markdown =
38-
if builtins.isString markdown then
39-
builtins.toFile "${lib.strings.replaceStrings [ "/" "-" ] (lib.lists.last loc)}.md" markdown
40-
else
41-
markdown;
42-
outFile = lib.strings.concatStringsSep "/" (loc ++ [ "index.md" ]);
43-
}
44-
// lib.optionalAttrs (page ? pages) {
45-
pages = elaboratePages loc pages;
46-
};
47-
48-
# Recursively normalise page nodes
49-
elaboratePages = prefix: builtins.mapAttrs (name: elaboratePage (prefix ++ [ name ]));
13+
pageConfiguration = lib.evalModules {
14+
modules = [
15+
pageSpecs
16+
{
17+
freeformType = lib.types.attrsOf (
18+
lib.types.submoduleWith {
19+
modules = [ ../modules/page.nix ];
20+
}
21+
);
22+
}
23+
];
24+
};
25+
pages = pageConfiguration.config;
5026

5127
# Collect all page nodes into a list of page entries
5228
collectPages =
5329
pages:
5430
builtins.concatMap (
55-
page:
56-
[ (builtins.removeAttrs page [ "pages" ]) ]
57-
++ lib.optionals (page ? pages) (collectPages page.pages)
31+
node:
32+
let
33+
children = builtins.removeAttrs node [ "_page" ];
34+
in
35+
lib.optional (node ? _page) node._page ++ lib.optionals (children != { }) (collectPages children)
5836
) (builtins.attrValues pages);
5937

6038
# Normalised page specs
61-
elaboratedPageSpecs = elaboratePages [ ] pageSpecs;
62-
pageList = collectPages elaboratedPageSpecs;
63-
pagesToRender = builtins.filter (page: page ? outFile) pageList;
64-
pagesWithFunctions = builtins.filter (page: page.file or null != null) pageList;
65-
in
66-
67-
runCommand "nixvim-lib-docs"
68-
{
69-
nativeBuildInputs = [
70-
nixdoc
71-
];
39+
pageList = collectPages pages;
40+
pagesToRender = builtins.filter (page: page.hasContent) pageList;
7241

73-
locations = writers.writeJSON "locations.json" (
74-
import ./function-locations.nix {
75-
inherit lib;
76-
rootPath = nixvim;
77-
functionSet = lib.extend nixvim.lib.overlay;
78-
pathsToScan = builtins.catAttrs "loc" pagesWithFunctions;
79-
revision = nixvim.rev or "main";
42+
result =
43+
runCommand "nixvim-lib-docs"
44+
{
45+
nativeBuildInputs = [
46+
nixdoc
47+
];
48+
49+
locations = writers.writeJSON "locations.json" (
50+
import ./function-locations.nix {
51+
inherit lib;
52+
rootPath = nixvim;
53+
functionSet = lib.extend nixvim.lib.overlay;
54+
pathsToScan = lib.pipe pageList [
55+
(map (x: x.functions))
56+
(builtins.filter (x: x.file != null))
57+
(map (x: x.loc))
58+
];
59+
revision = nixvim.rev or "main";
60+
}
61+
);
62+
63+
passthru.config = pageConfiguration;
64+
65+
passthru.menu = import ./menu.nix {
66+
inherit lib pages;
67+
};
68+
69+
passthru.pages = map (page: "${result}/${page.target}") pagesToRender;
8070
}
81-
);
82-
83-
passthru.menu = import ./menu.nix {
84-
inherit lib;
85-
pageSpecs = elaboratedPageSpecs;
86-
};
87-
88-
passthru.pages = builtins.listToAttrs (
89-
builtins.map (
90-
{ name, outFile, ... }:
91-
{
92-
inherit name;
93-
value = outFile;
71+
''
72+
function docgen {
73+
md_file="$1"
74+
in_file="$2"
75+
name="$3"
76+
out_file="$out/$4"
77+
title="$5"
78+
79+
if [[ -z "$in_file" ]]; then
80+
if [[ -z "$md_file" ]]; then
81+
>&2 echo "No markdown or nix file for $name"
82+
exit 1
83+
fi
84+
elif [[ -f "$in_file/default.nix" ]]; then
85+
in_file+="/default.nix"
86+
elif [[ ! -f "$in_file" ]]; then
87+
>&2 echo "File not found: $in_file"
88+
exit 1
89+
fi
90+
91+
if [[ -n "$in_file" ]]; then
92+
nixdoc \
93+
--file "$in_file" \
94+
--locs "$locations" \
95+
--category "$name" \
96+
--description "REMOVED BY TAIL" \
97+
--prefix "lib" \
98+
--anchor-prefix "" \
99+
| tail --lines +2 \
100+
> functions.md
101+
fi
102+
103+
default_heading="# $name"
104+
if [[ -n "$title" ]]; then
105+
default_heading+=": $title"
106+
fi
107+
108+
print_heading=true
109+
if [[ -f "$md_file" ]] && [[ "$(head --lines 1 "$md_file")" == '# '* ]]; then
110+
>&2 echo "NOTE: markdown file for $name starts with a <h1> heading. Skipping default heading \"$default_heading\"."
111+
>&2 echo " Found \"$(head --lines 1 "$md_file")\" in: $md_file"
112+
print_heading=false
113+
fi
114+
115+
mkdir -p $(dirname "$out_file")
116+
(
117+
if [[ "$print_heading" = true ]]; then
118+
echo "$default_heading"
119+
echo
120+
fi
121+
if [[ -f "$md_file" ]]; then
122+
cat "$md_file"
123+
echo
124+
fi
125+
if [[ -f functions.md ]]; then
126+
cat functions.md
127+
fi
128+
) > "$out_file"
94129
}
95-
) pagesToRender
96-
);
97-
}
98-
''
99-
function docgen {
100-
md_file="$1"
101-
in_file="$2"
102-
name="$3"
103-
out_file="$out/$4"
104-
title="$5"
105-
106-
if [[ -z "$in_file" ]]; then
107-
if [[ -z "$md_file" ]]; then
108-
>&2 echo "No markdown or nix file for $name"
109-
exit 1
110-
fi
111-
elif [[ -f "$in_file/default.nix" ]]; then
112-
in_file+="/default.nix"
113-
elif [[ ! -f "$in_file" ]]; then
114-
>&2 echo "File not found: $in_file"
115-
exit 1
116-
fi
117-
118-
if [[ -n "$in_file" ]]; then
119-
nixdoc \
120-
--file "$in_file" \
121-
--locs "$locations" \
122-
--category "$name" \
123-
--description "REMOVED BY TAIL" \
124-
--prefix "" \
125-
--anchor-prefix "" \
126-
| tail --lines +2 \
127-
> functions.md
128-
fi
129-
130-
default_heading="# $name"
131-
if [[ -n "$title" ]]; then
132-
default_heading+=": $title"
133-
fi
134-
135-
print_heading=true
136-
if [[ -f "$md_file" ]] && [[ "$(head --lines 1 "$md_file")" == '# '* ]]; then
137-
>&2 echo "NOTE: markdown file for $name starts with a <h1> heading. Skipping default heading \"$default_heading\"."
138-
>&2 echo " Found \"$(head --lines 1 "$md_file")\" in: $md_file"
139-
print_heading=false
140-
fi
141130
142-
mkdir -p $(dirname "$out_file")
143-
(
144-
if [[ "$print_heading" = true ]]; then
145-
echo "$default_heading"
146-
echo
147-
fi
148-
if [[ -f "$md_file" ]]; then
149-
cat "$md_file"
150-
echo
151-
fi
152-
if [[ -f functions.md ]]; then
153-
cat functions.md
154-
fi
155-
) > "$out_file"
156-
}
157-
158-
mkdir -p "$out"
159-
160-
${lib.concatMapStringsSep "\n" (
161-
{
162-
name,
163-
file,
164-
markdown,
165-
outFile,
166-
title ? "",
167-
...
168-
}:
169-
lib.escapeShellArgs [
170-
"docgen"
171-
"${lib.optionalString (markdown != null) markdown}" # md_file
172-
"${lib.optionalString (file != null) file}" # in_file
173-
name # name
174-
outFile # out_file
175-
title # title
176-
]
177-
) pagesToRender}
178-
''
131+
mkdir -p "$out"
132+
133+
${lib.concatMapStringsSep "\n" (
134+
{
135+
functions,
136+
source,
137+
target,
138+
title ? "",
139+
...
140+
}:
141+
lib.escapeShellArgs [
142+
"docgen"
143+
"${lib.optionalString (source != null) source}" # md_file
144+
"${lib.optionalString (functions.file != null) functions.file}" # in_file
145+
(lib.showAttrPath functions.loc) # name
146+
target # out_file
147+
title # title
148+
]
149+
) pagesToRender}
150+
'';
151+
in
152+
result

‎docs/lib/menu.nix‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,31 @@
11
{
22
lib,
3-
pageSpecs,
3+
pages,
44
indentSize ? " ",
55
}:
66
let
77
pageToLines =
8-
indent: parentName:
9-
{
10-
name,
11-
outFile ? "",
12-
pages ? { },
13-
...
14-
}:
8+
indent: parent: node:
159
let
16-
menuName = lib.strings.removePrefix (parentName + ".") name;
17-
children = builtins.attrValues pages;
10+
11+
children = lib.pipe node [
12+
(lib.flip builtins.removeAttrs [ "_page" ])
13+
builtins.attrValues
14+
];
1815
# Only add node to the menu if it has content or multiple children
19-
useNodeInMenu = outFile != "" || builtins.length children > 1;
20-
parentOfChildren = if useNodeInMenu then name else parentName;
16+
useNodeInMenu = node._page.target != "" || node._page.children > 1;
17+
nextParent = if useNodeInMenu then node else parent;
18+
nextIndent = if useNodeInMenu then indent + indentSize else indent;
19+
loc = lib.lists.removePrefix (parent._page.loc or [ ]) node._page.loc;
20+
menuName = lib.attrsets.showAttrPath loc;
2121
in
22-
lib.optional useNodeInMenu "${indent}- [${menuName}](${outFile})"
22+
lib.optional useNodeInMenu "${indent}- [${menuName}](${node._page.target})"
2323
++ lib.optionals (children != [ ]) (
24-
builtins.concatMap (pageToLines (indent + indentSize) parentOfChildren) children
24+
builtins.concatMap (pageToLines nextIndent nextParent) children
2525
);
2626
in
27-
lib.pipe pageSpecs [
27+
lib.pipe pages [
2828
builtins.attrValues
29-
(builtins.concatMap (pageToLines "" ""))
29+
(builtins.concatMap (pageToLines "" null))
3030
lib.concatLines
3131
]

‎docs/lib/pages.nix‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,19 @@
44
# If there is an issue parsing the file, the resulting markdown will not contain any function docs.
55

66
{
7-
lib.pages = {
8-
nixvim = {
7+
lib.nixvim = {
8+
_page = {
99
title = "Nixvim's functions";
10-
markdown = ./index.md;
10+
source = ./index.md;
11+
};
1112

12-
pages = {
13-
utils = {
14-
file = ../../lib/utils.nix;
15-
title = "utility functions";
16-
};
17-
lua = {
18-
file = ../../lib/to-lua.nix;
19-
title = "lua functions";
20-
};
21-
};
13+
utils._page = {
14+
title = "utility functions";
15+
functions.file = ../../lib/utils.nix;
16+
};
17+
lua._page = {
18+
title = "lua functions";
19+
functions.file = ../../lib/to-lua.nix;
2220
};
2321
};
2422
}

‎docs/man/default.nix‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ let
1212
../user-guide/faq.md
1313
../user-guide/config-examples.md
1414
]
15-
++ lib.mapAttrsToList (name: file: "${lib-docs}/${file}") lib-docs.pages;
15+
++ lib-docs.pages;
16+
1617
manHeader =
1718
runCommand "nixvim-general-doc-manpage"
1819
{

0 commit comments

Comments
 (0)