04f161a95b
The narrowed-source comment justified itself with "the muede-pc2 remote builder can reuse its cached result". mara, closing the issue I filed about that builder being unreachable: "this is expected behavior … depending on what network i am on different builders are available". So the machine is not a fact about this repo. The reasoning holds for whichever builder happens to be reachable, and a hostname in a comment is the thing that rots — the same class as the forge address that has been wrong twice.
249 lines
8.7 KiB
Nix
249 lines
8.7 KiB
Nix
{
|
|
pkgs,
|
|
lib,
|
|
self,
|
|
nixosSystem,
|
|
}:
|
|
# Nix options reference: `pkgs.nixosOptionsDoc` over two evaluated
|
|
# module trees, emitted as CommonMark (`host.md` + `agent.md` +
|
|
# `swarm.md` + `deploy.md`). The HTML + CSS for `/options/` is rendered
|
|
# downstream by the website repo, which owns the presentation and
|
|
# shares one stylesheet with the prose `/docs/` tree. Full pipeline +
|
|
# subtree-pick / output-tree rationale: docs/gotchas.md::Nix options
|
|
# reference.
|
|
#
|
|
# `swarm.md`/`deploy.md` split off `host.md` (mara: "move swarm options
|
|
# to new docs page... deploy.* is also one of the things that should be
|
|
# a sub page"): `services.hyperhive.swarm.*` was mixed — swarm-wide
|
|
# facts (name, domain, hives, ca) alongside "does THIS host run it"
|
|
# toggles — until `deploy.nix` moved every such toggle to its own flat
|
|
# `services.hyperhive.deploy.*` namespace. That reorg landed first
|
|
# (see deploy.nix's file-top comment); this is the docs-side follow-up
|
|
# now that `swarm.*` genuinely is swarm-wide-only.
|
|
let
|
|
# Content-addressed narrow source covering only the nix/ directory.
|
|
# `builtins.unsafeDiscardStringContext` strips `self`'s store-path
|
|
# context so `builtins.path` hashes only the nix/ file content, not
|
|
# the full flake source (Rust, frontend, markdown, …). Result: the
|
|
# docs drvs only change when a .nix file changes, not on every
|
|
# commit — a remote builder can reuse its cached result for any commit
|
|
# that doesn't touch nix/. (Named no machine: which builders are
|
|
# reachable depends on the network the deployer is on.)
|
|
nixSrc = builtins.path {
|
|
path = builtins.unsafeDiscardStringContext (toString self + "/nix");
|
|
name = "hyperhive-nix-src";
|
|
};
|
|
|
|
# Stub host system: every hyperhive subsystem `mkForce false` so
|
|
# heavy build inputs (matrix container, forge, etc.) stay out of
|
|
# the eval — only option *declarations* matter for the doc walk.
|
|
# Import the host-module aggregator from the content-addressed
|
|
# nixSrc; the package options (`services.hyperhive.c0re.package`
|
|
# etc.) carry no in-module defaults, but with hyperhive disabled
|
|
# nothing reads them, so no stubs are needed.
|
|
hostEval = nixosSystem {
|
|
system = pkgs.stdenv.hostPlatform.system;
|
|
modules = [
|
|
"${nixSrc}/host-modules"
|
|
(
|
|
{ lib, ... }:
|
|
{
|
|
fileSystems."/" = {
|
|
device = "/dev/null";
|
|
fsType = "tmpfs";
|
|
};
|
|
boot.loader.grub.enable = false;
|
|
system.stateVersion = "25.11";
|
|
services.hyperhive.enable = lib.mkForce false;
|
|
services.hyperhive.deploy.matrix.enable = lib.mkForce false;
|
|
}
|
|
)
|
|
];
|
|
};
|
|
|
|
# Agent module eval from the content-addressed nixSrc. Relative
|
|
# imports inside agent.nix (the ../agent-modules dir) resolve
|
|
# correctly against the nixSrc directory tree. `hyperhive.packages`
|
|
# stays unset — every option default that references it carries a
|
|
# `defaultText`, so the doc walk never forces the packages.
|
|
agentEval = nixosSystem {
|
|
system = pkgs.stdenv.hostPlatform.system;
|
|
modules = [
|
|
"${nixSrc}/templates/agent.nix"
|
|
];
|
|
};
|
|
|
|
# Rewrite option declaration paths from nix-store absolute paths to
|
|
# forge URLs so rendered docs link back to source.
|
|
# nixSrc is a content-addressed copy of nix/; strip its store prefix
|
|
# and prepend nix/ to recover the repo-relative path.
|
|
forgeRoot = "https://forge.darkest.space/hyperhive/hyperhive/src/branch/main";
|
|
nixSrcPrefix = builtins.unsafeDiscardStringContext (toString nixSrc + "/");
|
|
transformOptions =
|
|
opt:
|
|
opt
|
|
// {
|
|
declarations = map (
|
|
decl:
|
|
let
|
|
declStr = toString decl;
|
|
relPath =
|
|
if lib.hasPrefix nixSrcPrefix declStr then
|
|
"nix/" + lib.removePrefix nixSrcPrefix declStr
|
|
else
|
|
baseNameOf declStr;
|
|
in
|
|
{
|
|
url = "${forgeRoot}/${relPath}";
|
|
name = relPath;
|
|
}
|
|
) opt.declarations;
|
|
};
|
|
|
|
# Filter to a set of top-level subtree roots — keeps the rendered docs
|
|
# focused on hyperhive's surface instead of NixOS's 10k+ default
|
|
# options. Root choice matters: see docs/gotchas.md::Nix options
|
|
# reference for the services.hyperhive consolidation history.
|
|
pickSubtrees =
|
|
options: roots:
|
|
let
|
|
pick =
|
|
path:
|
|
if lib.hasAttrByPath path options then
|
|
lib.setAttrByPath path (lib.getAttrFromPath path options)
|
|
else
|
|
{ };
|
|
in
|
|
lib.foldl' lib.recursiveUpdate { } (map pick roots);
|
|
|
|
hostOptionsFull = pickSubtrees hostEval.options [
|
|
[
|
|
"services"
|
|
"hyperhive"
|
|
]
|
|
];
|
|
|
|
# `swarm.*` and `deploy.*` get their own pages below — drop them from
|
|
# the host tree rather than duplicating them here too. `pickSubtrees`
|
|
# only ever picked `services.hyperhive` for `hostOptionsFull` (nothing
|
|
# else lives under `services` in this tree), so a direct replacement
|
|
# is correct here — NOT `lib.recursiveUpdate`, which merges rather
|
|
# than deletes: a key present on the left and absent on the right
|
|
# survives the "update," which would silently keep `swarm`/`deploy`
|
|
# on `host.md` instead of dropping them.
|
|
hostOptions = {
|
|
services.hyperhive = builtins.removeAttrs hostOptionsFull.services.hyperhive [
|
|
"swarm"
|
|
"deploy"
|
|
];
|
|
};
|
|
|
|
swarmOptions = pickSubtrees hostEval.options [
|
|
[
|
|
"services"
|
|
"hyperhive"
|
|
"swarm"
|
|
]
|
|
];
|
|
|
|
deployOptions = pickSubtrees hostEval.options [
|
|
[
|
|
"services"
|
|
"hyperhive"
|
|
"deploy"
|
|
]
|
|
];
|
|
|
|
agentOptions = pickSubtrees agentEval.options [
|
|
[ "hyperhive" ]
|
|
];
|
|
|
|
hostDoc = pkgs.nixosOptionsDoc {
|
|
options = hostOptions;
|
|
inherit transformOptions;
|
|
};
|
|
|
|
swarmDoc = pkgs.nixosOptionsDoc {
|
|
options = swarmOptions;
|
|
inherit transformOptions;
|
|
};
|
|
|
|
deployDoc = pkgs.nixosOptionsDoc {
|
|
options = deployOptions;
|
|
inherit transformOptions;
|
|
};
|
|
|
|
agentDoc = pkgs.nixosOptionsDoc {
|
|
options = agentOptions;
|
|
inherit transformOptions;
|
|
};
|
|
|
|
# CommonMark `.md` is the source of truth and the only output. HTML
|
|
# rendering + theming lives in the website repo (it owns the
|
|
# presentation + shares one stylesheet across `/options/` and
|
|
# `/docs/`); this flake just emits the option reference as markdown.
|
|
mkMarkdownPage =
|
|
name: title: doc:
|
|
pkgs.runCommand "hyperhive-${name}.md" { } ''
|
|
{
|
|
echo "# ${title}"
|
|
echo
|
|
echo "<!-- Auto-generated from the hyperhive flake."
|
|
echo " Source: nix/docs/default.nix · regenerate with"
|
|
echo " \`nix build .#${name}\` -->"
|
|
echo
|
|
cat ${doc.optionsCommonMark}
|
|
} > $out
|
|
'';
|
|
|
|
# Bundle landing page — a short markdown index pointing at the four
|
|
# reference pages.
|
|
indexMD = pkgs.writeText "hyperhive-options-index.md" ''
|
|
# hyperhive — nix options reference
|
|
|
|
Auto-generated from the hyperhive flake. Four reading paths:
|
|
|
|
- [host options](host.md) — options exposed by
|
|
`hyperhive.nixosModules.default` to operator host configurations
|
|
(`services.hyperhive.{enable,domain,c0re,gateway,tls,network}.*`).
|
|
- [swarm options](swarm.md) — swarm-wide facts, identical on every
|
|
host in the swarm (`services.hyperhive.swarm.{name,domain,hives,
|
|
ca,forge,matrix}.*`).
|
|
- [deploy options](deploy.md) — this host's own deployment
|
|
decisions, necessarily different per host
|
|
(`services.hyperhive.deploy.*` — does *this* machine run
|
|
grafana, the swarm controller, authelia, …).
|
|
- [per-agent options](agent.md) — options declared in
|
|
`nix/agent-modules/`, visible from every `agent.nix`
|
|
(`hyperhive.model`, `hyperhive.allowedRecipients`,
|
|
`hyperhive.extraMcpServers`, `hyperhive.frontend.*`,
|
|
`hyperhive.forge.*`, `hyperhive.matrix.*`, `hyperhive.gui.*`).
|
|
|
|
Regenerate with `nix build .#docs` (bundle), `.#docs-host`,
|
|
`.#docs-swarm`, `.#docs-deploy`, or `.#docs-agent`. Consumed by the
|
|
website repo to render `/options/`.
|
|
'';
|
|
|
|
hostMD = mkMarkdownPage "docs-host" "hyperhive — host options" hostDoc;
|
|
swarmMD = mkMarkdownPage "docs-swarm" "hyperhive — swarm options" swarmDoc;
|
|
deployMD = mkMarkdownPage "docs-deploy" "hyperhive — deploy options" deployDoc;
|
|
agentMD = mkMarkdownPage "docs-agent" "hyperhive — per-agent options" agentDoc;
|
|
in
|
|
{
|
|
host = hostMD;
|
|
swarm = swarmMD;
|
|
deploy = deployMD;
|
|
agent = agentMD;
|
|
|
|
# Bundle of the option reference as markdown. The website renders
|
|
# these `.md` to themed HTML for `/options/`; standalone consumers
|
|
# get the CommonMark source directly.
|
|
bundle = pkgs.runCommand "hyperhive-options-docs" { } ''
|
|
mkdir -p $out
|
|
cp ${indexMD} $out/index.md
|
|
cp ${hostMD} $out/host.md
|
|
cp ${swarmMD} $out/swarm.md
|
|
cp ${deployMD} $out/deploy.md
|
|
cp ${agentMD} $out/agent.md
|
|
'';
|
|
}
|