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