mirror of
https://github.com/nix-community/nixvim.git
synced 2025-12-07 17:41:04 +01:00
docs/modules: init
Modules to represent pages in the docs
This commit is contained in:
Matt Sturgeon
parent
9faa339d9e
commit
4414d8aa14
6 changed files with 309 additions and 187 deletions
|
|
@ -6,173 +6,147 @@
|
|||
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 ]));
|
||||
pageConfiguration = lib.evalModules {
|
||||
modules = [
|
||||
pageSpecs
|
||||
{
|
||||
freeformType = lib.types.attrsOf (
|
||||
lib.types.submoduleWith {
|
||||
modules = [ ../modules/page.nix ];
|
||||
}
|
||||
);
|
||||
}
|
||||
];
|
||||
};
|
||||
pages = pageConfiguration.config;
|
||||
|
||||
# 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)
|
||||
node:
|
||||
let
|
||||
children = builtins.removeAttrs node [ "_page" ];
|
||||
in
|
||||
lib.optional (node ? _page) node._page ++ lib.optionals (children != { }) (collectPages children)
|
||||
) (builtins.attrValues pages);
|
||||
|
||||
# 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";
|
||||
}
|
||||
);
|
||||
|
||||
passthru.menu = import ./menu.nix {
|
||||
inherit lib;
|
||||
pageSpecs = elaboratedPageSpecs;
|
||||
};
|
||||
|
||||
passthru.pages = builtins.listToAttrs (
|
||||
builtins.map (
|
||||
{ name, outFile, ... }:
|
||||
{
|
||||
inherit name;
|
||||
value = outFile;
|
||||
}
|
||||
) 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" (
|
||||
result =
|
||||
runCommand "nixvim-lib-docs"
|
||||
{
|
||||
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}
|
||||
''
|
||||
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 = pageConfiguration;
|
||||
|
||||
passthru.menu = import ./menu.nix {
|
||||
inherit lib pages;
|
||||
};
|
||||
|
||||
passthru.pages = map (page: "${result}/${page.target}") 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 "lib" \
|
||||
--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" (
|
||||
{
|
||||
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) # name
|
||||
target # out_file
|
||||
title # title
|
||||
]
|
||||
) pagesToRender}
|
||||
'';
|
||||
in
|
||||
result
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue