188f3ea5ec
Part of the docs-migration chore (issue #708). Remove GitHub issue numbers from inline comments, option descriptions, and rustdoc — these are contextless noise for anyone reading the code without access to the original discussions. Replace with prose that captures the same rationale directly. No functional change. Build still clean (cargo check passes).
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 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
|
|
'';
|
|
}
|