{ 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 "" 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 '' echo '' echo '' echo '' echo '' echo '${title}' echo '' echo '' echo '' echo '' echo '
' echo '

${title}

' echo '

Auto-generated from the hyperhive flake. Source: nix/docs/default.nix.

' cmark-gfm ${doc.optionsCommonMark} echo '
' echo '' echo '' echo '' } > $out ''; # Landing page — same template shape, hand-authored intro + cross-links. indexHTML = pkgs.runCommand "hyperhive-docs-index.html" { } '' { echo '' echo '' echo '' echo '' echo '' echo 'hyperhive — nix options reference' echo '' echo '' echo '' echo '' echo '
' echo '

hyperhive — nix options reference

' echo '

Auto-generated from the hyperhive flake. Two reading paths:

' echo '

host options

' echo '

Options exposed by hyperhive.nixosModules.default to operator host configurations: services.hyperhive.{enable,domain,c0re,forge,matrix,gateway}.*.

' echo '

agent options

' echo '

Per-agent options declared in nix/templates/harness-base.nix and visible from every agent.nix: hyperhive.model, hyperhive.allowedRecipients, hyperhive.extraMcpServers, hyperhive.frontend.*, hyperhive.forge.*, hyperhive.matrix.*, hyperhive.gui.*.

' echo '

Regenerate

' echo '
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)
' echo '

The bundle also ships .md versions of each page (host.md, agent.md) — same content, source-of-truth shape — alongside the HTML.

' echo '
' echo '' echo '' echo '' } > $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 ''; }