Skip to content

docs/lib: generalise using the module system #3706

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 30, 2025
Merged

docs/lib: generalise using the module system #3706

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6684d79
docs/modules: init
MattSturgeon May 20, 2025
2c40720
docs/lib: simplify default title-heading
MattSturgeon Sep 23, 2025
01631a3
docs/lib: rename 'name' → 'category'
MattSturgeon Sep 23, 2025
c99d6f2
docs/lib: generalise `menu` impl using module system
MattSturgeon Sep 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
276 changes: 120 additions & 156 deletions docs/lib/default.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,173 +6,137 @@
writers,
nixdoc,
nixvim,
pageSpecs ? import ./pages.nix,
pageSpecs ? ./pages.nix,
}:

let
# Some pages are just menu entries, others have an actual markdown page that
# needs rendering.
shouldRenderPage = page: page ? file || page ? markdown;

# Normalise a page node, recursively normalise its children
elaboratePage =
loc:
{
title ? "",
markdown ? null,
file ? null,
pages ? { },
}@page:
{
name = lib.attrsets.showAttrPath loc;
loc = lib.throwIfNot (
builtins.head loc == "lib"
) "All pages must be within `lib`, unexpected root `${builtins.head loc}`" (builtins.tail loc);
}
// lib.optionalAttrs (shouldRenderPage page) {
inherit
file
title
;
markdown =
if builtins.isString markdown then
builtins.toFile "${lib.strings.replaceStrings [ "/" "-" ] (lib.lists.last loc)}.md" markdown
else
markdown;
outFile = lib.strings.concatStringsSep "/" (loc ++ [ "index.md" ]);
}
// lib.optionalAttrs (page ? pages) {
pages = elaboratePages loc pages;
};

# Recursively normalise page nodes
elaboratePages = prefix: builtins.mapAttrs (name: elaboratePage (prefix ++ [ name ]));
menuConfiguration = lib.evalModules {
modules = [
pageSpecs
../modules/menu.nix
];
};
cfg = menuConfiguration.config;
pages = cfg.functions;

# Collect all page nodes into a list of page entries
collectPages =
pages:
builtins.concatMap (
page:
[ (builtins.removeAttrs page [ "pages" ]) ]
++ lib.optionals (page ? pages) (collectPages page.pages)
) (builtins.attrValues pages);
node:
let
children = builtins.removeAttrs node [ "_page" ];
in
lib.optional (node ? _page) node._page ++ lib.optionals (children != { }) (collectPages children)
) (builtins.attrValues (builtins.removeAttrs pages [ "_category" ]));

# Normalised page specs
elaboratedPageSpecs = elaboratePages [ ] pageSpecs;
pageList = collectPages elaboratedPageSpecs;
pagesToRender = builtins.filter (page: page ? outFile) pageList;
pagesWithFunctions = builtins.filter (page: page.file or null != null) pageList;
in
pageList = collectPages pages;
pagesToRender = builtins.filter (page: page.hasContent) pageList;

runCommand "nixvim-lib-docs"
{
nativeBuildInputs = [
nixdoc
];

locations = writers.writeJSON "locations.json" (
import ./function-locations.nix {
inherit lib;
rootPath = nixvim;
functionSet = lib.extend nixvim.lib.overlay;
pathsToScan = builtins.catAttrs "loc" pagesWithFunctions;
revision = nixvim.rev or "main";
result =
runCommand "nixvim-lib-docs"
{
nativeBuildInputs = [
nixdoc
];

locations = writers.writeJSON "locations.json" (
import ./function-locations.nix {
inherit lib;
rootPath = nixvim;
functionSet = lib.extend nixvim.lib.overlay;
pathsToScan = lib.pipe pageList [
(map (x: x.functions))
(builtins.filter (x: x.file != null))
(map (x: x.loc))
];
revision = nixvim.rev or "main";
}
);

passthru.config = menuConfiguration;

passthru.menu = cfg._menu.text;

passthru.pages = map (page: "${result}/${page.target}") pagesToRender;
}
);

passthru.menu = import ./menu.nix {
inherit lib;
pageSpecs = elaboratedPageSpecs;
};

passthru.pages = builtins.listToAttrs (
builtins.map (
{ name, outFile, ... }:
{
inherit name;
value = outFile;
''
function docgen {
md_file="$1"
in_file="$2"
category="$3"
out_file="$out/$4"
title="$5"

if [[ -z "$in_file" ]]; then
if [[ -z "$md_file" ]]; then
>&2 echo "No markdown or nix file for $category"
exit 1
fi
elif [[ -f "$in_file/default.nix" ]]; then
in_file+="/default.nix"
elif [[ ! -f "$in_file" ]]; then
>&2 echo "File not found: $in_file"
exit 1
fi

if [[ -n "$in_file" ]]; then
nixdoc \
--file "$in_file" \
--locs "$locations" \
--category "$category" \
--description "REMOVED BY TAIL" \
--prefix "lib" \
--anchor-prefix "" \
| tail --lines +2 \
> functions.md
fi

print_title=true
if [[ -f "$md_file" ]] && [[ "$(head --lines 1 "$md_file")" == '# '* ]]; then
if [[ -n "$title" ]]; then
>&2 echo "NOTE: markdown file for $category starts with a <h1> heading. Skipping title \"$title\"."
>&2 echo " Found \"$(head --lines 1 "$md_file")\" in: $md_file"
fi
print_title=false
fi

mkdir -p $(dirname "$out_file")
(
if [[ "$print_title" = true ]]; then
echo "# $title"
echo
fi
if [[ -f "$md_file" ]]; then
cat "$md_file"
echo
fi
if [[ -f functions.md ]]; then
cat functions.md
fi
) > "$out_file"
}
) pagesToRender
);
}
''
function docgen {
md_file="$1"
in_file="$2"
name="$3"
out_file="$out/$4"
title="$5"

if [[ -z "$in_file" ]]; then
if [[ -z "$md_file" ]]; then
>&2 echo "No markdown or nix file for $name"
exit 1
fi
elif [[ -f "$in_file/default.nix" ]]; then
in_file+="/default.nix"
elif [[ ! -f "$in_file" ]]; then
>&2 echo "File not found: $in_file"
exit 1
fi

if [[ -n "$in_file" ]]; then
nixdoc \
--file "$in_file" \
--locs "$locations" \
--category "$name" \
--description "REMOVED BY TAIL" \
--prefix "" \
--anchor-prefix "" \
| tail --lines +2 \
> functions.md
fi

default_heading="# $name"
if [[ -n "$title" ]]; then
default_heading+=": $title"
fi

print_heading=true
if [[ -f "$md_file" ]] && [[ "$(head --lines 1 "$md_file")" == '# '* ]]; then
>&2 echo "NOTE: markdown file for $name starts with a <h1> heading. Skipping default heading \"$default_heading\"."
>&2 echo " Found \"$(head --lines 1 "$md_file")\" in: $md_file"
print_heading=false
fi

mkdir -p $(dirname "$out_file")
(
if [[ "$print_heading" = true ]]; then
echo "$default_heading"
echo
fi
if [[ -f "$md_file" ]]; then
cat "$md_file"
echo
fi
if [[ -f functions.md ]]; then
cat functions.md
fi
) > "$out_file"
}

mkdir -p "$out"

${lib.concatMapStringsSep "\n" (
{
name,
file,
markdown,
outFile,
title ? "",
...
}:
lib.escapeShellArgs [
"docgen"
"${lib.optionalString (markdown != null) markdown}" # md_file
"${lib.optionalString (file != null) file}" # in_file
name # name
outFile # out_file
title # title
]
) pagesToRender}
''
mkdir -p "$out"

${lib.concatMapStringsSep "\n" (
{
functions,
source,
target,
title ? "",
...
}:
lib.escapeShellArgs [
"docgen"
"${lib.optionalString (source != null) source}" # md_file
"${lib.optionalString (functions.file != null) functions.file}" # in_file
(lib.showAttrPath functions.loc) # category
target # out_file
title # title
]
) pagesToRender}
'';
in
result
31 changes: 0 additions & 31 deletions docs/lib/menu.nix
View file
Open in desktop

This file was deleted.

28 changes: 15 additions & 13 deletions docs/lib/pages.nix
View file
Open in desktop
Copy link
Member

@traxys traxys Sep 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah so this means that we can "easily" add documentation "anywhere" in the module system, right?

Copy link
Member Author

@MattSturgeon MattSturgeon Sep 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah. I tried to come up with a structured way of representing a mdbook menu tree.

There are other possible approaches. E.g. we could have a flat structure with each element having a "loc" attribute.

Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,22 @@
# If there is an issue parsing the file, the resulting markdown will not contain any function docs.

{
lib.pages = {
nixvim = {
title = "Nixvim's functions";
markdown = ./index.md;
functions = {
_category.name = "Functions";

pages = {
utils = {
file = ../../lib/utils.nix;
title = "utility functions";
};
lua = {
file = ../../lib/to-lua.nix;
title = "lua functions";
};
lib.nixvim = {
_page = {
title = "lib.nixvim: Nixvim's functions";
source = ./index.md;
};

utils._page = {
title = "lib.nixvim.utils: utility functions";
functions.file = ../../lib/utils.nix;
};
lua._page = {
title = "lib.nixvim.lua: lua functions";
functions.file = ../../lib/to-lua.nix;
};
};
};
Expand Down
3 changes: 2 additions & 1 deletion docs/man/default.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ let
../user-guide/faq.md
../user-guide/config-examples.md
]
++ lib.mapAttrsToList (name: file: "${lib-docs}/${file}") lib-docs.pages;
++ lib-docs.pages;

manHeader =
runCommand "nixvim-general-doc-manpage"
{
Expand Down
2 changes: 0 additions & 2 deletions docs/mdbook/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@
- [Configuration examples](./user-guide/config-examples.md)
- [Lazy Loading](./user-guide/lazy-loading.md)

# Functions

@FUNCTIONS_MENU@

# Platforms
Expand Down
Loading