docs: render zola pages in clan-core flake
checks / check-links (pull_request) Successful in 14s Details
checks / checks-impure (pull_request) Successful in 1m51s Details
checks / checks (pull_request) Successful in 3m41s Details

This integrates the generated options docs part of our website into the clan-core project. This is better than having it in a separate repos because we want to lear about breakages as early as possible.

Changes which break the documentation should be blocked by this early on
This commit is contained in:
DavHau 2024-03-31 12:33:31 +07:00
parent 62f201696d
commit 492256ec54
3 changed files with 106 additions and 21 deletions

View File

@ -5,6 +5,8 @@
...
}:
{
imports = [ ./zola-pages.nix ];
perSystem =
{ pkgs, ... }:
let
@ -16,20 +18,22 @@
clanCoreNixosModules = [ self.nixosModules.clanCore ] ++ allNixosModules;
# options = modules: (inputs.nixpkgs.legacyPackages.x86_64-linux.nixos { imports = modules; }).options;
options =
modules:
(lib.evalModules {
modules = modules;
# modules = modules ++ ["${inputs.nixpkgs}/nixos/modules/misc/assertions.nix"];
# specialArgs = { pkgs = pkgs; };
}).options;
# TODO: optimally we would not have to evaluate all nixos modules for every page
# but some of our module options secretly depend on nixos modules.
# We would have to get rid of these implicit dependencies and make them explicit
clanCoreNixos = pkgs.nixos { imports = clanCoreNixosModules; };
# using extendModules here instead of re-evaluating nixos every time
# improves eval performance slightly (10%)
options = modules: (clanCoreNixos.extendModules { inherit modules; }).options;
docs =
options:
pkgs.nixosOptionsDoc {
options = options;
warningsAreErrors = false;
# transform each option so that the declaration link points to git.clan.lol
# and not to the /nix/store
transformOptions =
opt:
opt
@ -53,20 +57,13 @@
outputsFor = name: docs: { packages."docs-md-${name}" = docs.optionsCommonMark; };
clanModulesPages = lib.flip lib.mapAttrsToList self.clanModules (
name: module:
outputsFor "module-${name}" (
docs (options ([ module ] ++ clanCoreNixosModules)).clan.${name} or { }
)
name: module: outputsFor "module-${name}" (docs ((options [ module ]).clan.${name} or { }))
);
in
{
imports =
clanModulesPages
# uncomment to render clanCore top-level options as extra pages
# ++ clanCorePages
++ [
# renders all clanCore options as a single page
(outputsFor "core-options" (docs (options clanCoreNixosModules).clanCore))
];
imports = clanModulesPages ++ [
# renders all clanCore options in a single page
(outputsFor "core-options" (docs (options [ ]).clanCore))
];
};
}

View File

@ -0,0 +1,88 @@
{
perSystem =
{
lib,
pkgs,
self',
...
}:
let
getMdPages =
prefix:
let
mdDocs' = lib.filterAttrs (name: _: lib.hasPrefix prefix name) self'.packages;
mdDocs = lib.mapAttrs' (name: pkg: lib.nameValuePair (lib.removePrefix prefix name) pkg) mdDocs';
in
if mdDocs != { } then
mdDocs
else
throw ''
Error: no markdown files found in clan-core.packages' with prefix "${prefix}"
'';
makeZolaIndexMd =
title: weight:
pkgs.writeText "_index.md" ''
+++
title = "${title}"
template = "docs/section.html"
weight = ${toString weight}
sort_by = "title"
draft = false
+++
'';
makeZolaPages =
{
sectionTitle,
files,
makeIntro ? _name: "",
weight ? 9999,
}:
pkgs.runCommand "zola-pages-clan-core" { } ''
mkdir $out
# create new section via _index.md
cp ${makeZolaIndexMd sectionTitle weight} $out/_index.md
# generate zola compatible md files for each nixos options md
${lib.concatStringsSep "\n" (
lib.flip lib.mapAttrsToList files (
name: md: ''
# generate header for zola with title, template, weight
title="${name}"
echo -e "+++\ntitle = \"$title\"\ntemplate = \"docs/page.html\"\nweight = 0\n+++" > "$out/${name}.md"
cat <<EOF >> "$out/${name}.md"
${makeIntro name}
EOF
# append everything from the nixpkgs generated md file
cat "${md}" >> "$out/${name}.md"
''
)
)}
'';
in
{
packages.docs-zola-pages-core = makeZolaPages {
sectionTitle = "cLAN Core Reference";
files = getMdPages "docs-md-core-";
weight = 20;
};
packages.docs-zola-pages-modules = makeZolaPages {
sectionTitle = "cLAN Modules Reference";
files = getMdPages "docs-md-module-";
weight = 25;
makeIntro = name: ''
To use this module, import it like this:
\`\`\`nix
{config, lib, inputs, ...}: {
imports = [inputs.clan-core.clanModules.${name}];
# ...
}
\`\`\`
'';
};
};
}

View File

@ -36,7 +36,7 @@
./checks/flake-module.nix
./clanModules/flake-module.nix
./devShell.nix
./docs/flake-module.nix
./docs/flake-module
./formatter.nix
./lib/flake-module.nix
./nixosModules/flake-module.nix