db2a48cde6
- assets.nix: cargo-cache-invalidation rationale → "Split asset derivations away from the rust workspace" section. - templates/weston-vnc.nix: port allocation, weston bind-address quirk, PAM service name, Type=simple choice, idle-time=0 → "Weston VNC compositor (per-agent hyperhive.gui.enable)" section. - docs/default.nix: rendering pipeline + subtree-pick + output-tree history → "Nix options reference" section. In-code comments trimmed to short purpose statements + docs pointers. description = '' blocks (operator-facing options docs) preserved per iris #718. `nix flake check` + `nix build .#docs` clean.
217 lines
7.8 KiB
Nix
217 lines
7.8 KiB
Nix
{
|
|
pkgs,
|
|
lib,
|
|
self,
|
|
nixosSystem,
|
|
}:
|
|
# Nix options reference: `pkgs.nixosOptionsDoc` over two evaluated
|
|
# module trees, rendered as CommonMark + HTML + bundled static site
|
|
# the operator's nginx serves from `/options/`. Full pipeline +
|
|
# subtree-pick / output-tree rationale: docs/gotchas.md::Nix options
|
|
# reference.
|
|
let
|
|
# 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.
|
|
hostEval = nixosSystem {
|
|
system = pkgs.stdenv.hostPlatform.system;
|
|
modules = [
|
|
self.nixosModules.default
|
|
(
|
|
{ lib, ... }:
|
|
{
|
|
nixpkgs.overlays = [ self.overlays.default ];
|
|
fileSystems."/" = {
|
|
device = "/dev/null";
|
|
fsType = "tmpfs";
|
|
};
|
|
boot.loader.grub.enable = false;
|
|
system.stateVersion = "25.11";
|
|
services.hyperhive.enable = lib.mkForce false;
|
|
services.hyperhive.forge.enable = lib.mkForce false;
|
|
services.hyperhive.matrix.enable = lib.mkForce false;
|
|
services.hyperhive.gateway.enable = lib.mkForce false;
|
|
}
|
|
)
|
|
];
|
|
};
|
|
|
|
# Reuse the already-evaluated agent-base config — its options tree is
|
|
# identical to what a real agent container sees, no second eval needed.
|
|
agentEval = self.nixosConfigurations.agent-base;
|
|
|
|
# Rewrite option declaration paths from nix-store absolute paths to
|
|
# forge URLs so rendered docs link back to source.
|
|
forgeRoot = "https://forge.darkest.space/hyperhive/hyperhive/src/branch/main";
|
|
storePrefix = toString self + "/";
|
|
transformOptions =
|
|
opt:
|
|
opt
|
|
// {
|
|
declarations = map (
|
|
decl:
|
|
let
|
|
declStr = toString decl;
|
|
relPath =
|
|
if lib.hasPrefix storePrefix declStr then
|
|
lib.removePrefix storePrefix 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 post-#615 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);
|
|
|
|
hostOptions = pickSubtrees hostEval.options [
|
|
[
|
|
"services"
|
|
"hyperhive"
|
|
]
|
|
];
|
|
|
|
agentOptions = pickSubtrees agentEval.options [
|
|
[ "hyperhive" ]
|
|
];
|
|
|
|
hostDoc = pkgs.nixosOptionsDoc {
|
|
options = hostOptions;
|
|
inherit transformOptions;
|
|
};
|
|
|
|
agentDoc = pkgs.nixosOptionsDoc {
|
|
options = agentOptions;
|
|
inherit transformOptions;
|
|
};
|
|
|
|
# CommonMark .md = source of truth; HTML is rendered from this.
|
|
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
|
|
'';
|
|
|
|
# Loaded as text so it's editable with normal CSS tooling and
|
|
# inlined into every page (no second-fetch dependency).
|
|
styleCSS = builtins.readFile ./style.css;
|
|
|
|
# CommonMark → cmark-gfm → minimal template, inline CSS, relative links.
|
|
mkHtmlPage =
|
|
name: title: doc:
|
|
pkgs.runCommand "hyperhive-${name}.html" { nativeBuildInputs = [ pkgs.cmark-gfm ]; } ''
|
|
{
|
|
echo '<!doctype html>'
|
|
echo '<html lang="en">'
|
|
echo '<head>'
|
|
echo '<meta charset="utf-8">'
|
|
echo '<meta name="viewport" content="width=device-width, initial-scale=1">'
|
|
echo '<title>${title}</title>'
|
|
echo '<style>'
|
|
cat ${pkgs.writeText "hyperhive-docs-style.css" styleCSS}
|
|
echo '</style>'
|
|
echo '</head>'
|
|
echo '<body>'
|
|
echo '<nav>'
|
|
echo '<a href="./index.html">index</a>'
|
|
echo '<a href="./host.html">host options</a>'
|
|
echo '<a href="./agent.html">agent options</a>'
|
|
echo '</nav>'
|
|
echo '<main>'
|
|
echo '<h1>${title}</h1>'
|
|
echo '<p><em>Auto-generated from the hyperhive flake. Source: <a href="${forgeRoot}/nix/docs/default.nix">nix/docs/default.nix</a>.</em></p>'
|
|
cmark-gfm ${doc.optionsCommonMark}
|
|
echo '</main>'
|
|
echo '<footer>'
|
|
echo '<p>hyperhive · <a href="${forgeRoot}">source</a></p>'
|
|
echo '</footer>'
|
|
echo '</body>'
|
|
echo '</html>'
|
|
} > $out
|
|
'';
|
|
|
|
# Landing page — same template shape, hand-authored intro + cross-links.
|
|
indexHTML = pkgs.runCommand "hyperhive-docs-index.html" { } ''
|
|
{
|
|
echo '<!doctype html>'
|
|
echo '<html lang="en">'
|
|
echo '<head>'
|
|
echo '<meta charset="utf-8">'
|
|
echo '<meta name="viewport" content="width=device-width, initial-scale=1">'
|
|
echo '<title>hyperhive — nix options reference</title>'
|
|
echo '<style>'
|
|
cat ${pkgs.writeText "hyperhive-docs-style.css" styleCSS}
|
|
echo '</style>'
|
|
echo '</head>'
|
|
echo '<body>'
|
|
echo '<nav>'
|
|
echo '<a href="./index.html">index</a>'
|
|
echo '<a href="./host.html">host options</a>'
|
|
echo '<a href="./agent.html">agent options</a>'
|
|
echo '</nav>'
|
|
echo '<main>'
|
|
echo '<h1>hyperhive — nix options reference</h1>'
|
|
echo '<p>Auto-generated from the <a href="${forgeRoot}">hyperhive flake</a>. Two reading paths:</p>'
|
|
echo '<h3><a href="./host.html">host options</a></h3>'
|
|
echo '<p>Options exposed by <code>hyperhive.nixosModules.default</code> to operator host configurations: <code>services.hyperhive.{enable,domain,c0re,forge,matrix,gateway}.*</code>.</p>'
|
|
echo '<h3><a href="./agent.html">agent options</a></h3>'
|
|
echo '<p>Per-agent options declared in <code>nix/templates/harness-base.nix</code> and visible from every <code>agent.nix</code>: <code>hyperhive.model</code>, <code>hyperhive.allowedRecipients</code>, <code>hyperhive.extraMcpServers</code>, <code>hyperhive.frontend.*</code>, <code>hyperhive.forge.*</code>, <code>hyperhive.matrix.*</code>, <code>hyperhive.gui.*</code>.</p>'
|
|
echo '<h3>Regenerate</h3>'
|
|
echo '<pre><code>nix build .#docs # bundled static site (index + host + agent)'
|
|
echo 'nix build .#docs-host # host page only (HTML)'
|
|
echo 'nix build .#docs-agent # agent page only (HTML)</code></pre>'
|
|
echo '<p>The bundle also ships <code>.md</code> versions of each page (<code>host.md</code>, <code>agent.md</code>) — same content, source-of-truth shape — alongside the HTML.</p>'
|
|
echo '</main>'
|
|
echo '<footer>'
|
|
echo '<p>hyperhive · <a href="${forgeRoot}">source</a></p>'
|
|
echo '</footer>'
|
|
echo '</body>'
|
|
echo '</html>'
|
|
} > $out
|
|
'';
|
|
|
|
hostHTML = mkHtmlPage "docs-host" "hyperhive — host options" hostDoc;
|
|
agentHTML = mkHtmlPage "docs-agent" "hyperhive — per-agent options" agentDoc;
|
|
hostMD = mkMarkdownPage "docs-host" "hyperhive — host options" hostDoc;
|
|
agentMD = mkMarkdownPage "docs-agent" "hyperhive — per-agent options" agentDoc;
|
|
in
|
|
{
|
|
host = hostHTML;
|
|
agent = agentHTML;
|
|
|
|
# Bundled static site nginx serves at `/options/`. Asset paths are
|
|
# all relative so the prefix can change without rebuild.
|
|
bundle = pkgs.runCommand "hyperhive-options-docs" { } ''
|
|
mkdir -p $out
|
|
cp ${indexHTML} $out/index.html
|
|
cp ${hostHTML} $out/host.html
|
|
cp ${agentHTML} $out/agent.html
|
|
cp ${hostMD} $out/host.md
|
|
cp ${agentMD} $out/agent.md
|
|
'';
|
|
}
|