vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

reference-docs: virtualize the options bundle under docs/options/, like crates/

Browse source 
mara on hyperhive/website#59 ("is this slice 1? i expected the options
to fold into the main docs sidebar as well so that you have one all
docs tree" / "the same thing already happens: crate readmes get
included as well. add the virtual options dir"): apply the exact
technique already used for docs/crates/<crate>.md to the nixosOptionsDoc
bundle (packages.docs) — project it into the reference-docs tree at
docs/options/*.md rather than leaving it a wholly separate flake output
options.nix has to fetch and render on its own pipeline.

Simpler than the crates/ case: the options bundle is already
self-contained CommonMark with no relative doc-links needing rewriting
(nixosOptionsDoc's transformOptions already points every option
declaration at an absolute forge URL), so this is a straight
recursive copy, not a per-file sed pass.

website's docs.nix needs no changes to pick this up — its sidebar walk
is already generic over subdirectories, same reason the earlier
crates/ virtualization needed none. The website-side follow-up (has
docs.nix render these instead of options.nix's separate pipeline, and
what that means for the current /options/ URL) is a separate change on
that repo, not touched here.
This commit is contained in:
iris 2026-09-02 02:15:52 +02:00 • committed by mara
commit 5dce46830d
2 changed files with 23 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

13
nix/packages/default.nix
View file

@ -221,11 +221,14 @@ in
# agents read it in-container (added as a claude additional
# directory) and the website repo reuses it as a flake input,
# neither of which needs the branding/prompt assets. See
# ./reference-docs.nix. (`docs` below is the auto-generated
# nix-options reference, a different artifact.) `self` is needed to
# read each workspace crate's own README.md into the virtual
# `crates/` subdir.
reference-docs = pkgs.callPackage ./reference-docs.nix { inherit self; };
# ./reference-docs.nix. `self` is needed to read each workspace
# crate's own README.md into the virtual `crates/` subdir;
# `docsAttrs.bundle` (the same tree `docs` below exposes standalone)
# is projected into the virtual `options/` subdir the same way.
reference-docs = pkgs.callPackage ./reference-docs.nix {
inherit self;
optionsMd = docsAttrs.bundle;
};
# XDG icon set + .desktop entries for hyperhive processes.
# Narrow input: only the branding SVG, so unrelated source changes
# don't bust this derivation's cache.

30
nix/packages/reference-docs.nix
View file

@ -2,6 +2,7 @@
stdenv,
lib,
self,
optionsMd,
}:
# The repo `docs/` markdown tree, shipped as a standalone derivation so
@ -10,21 +11,19 @@
# prompt assets they don't need, and so the `hyperhive/website` repo can
# reuse the exact same tree as a flake input.
#
# The docs/ tree is copied verbatim (never transformed). On top of that,
# `$out/crates/<crate>.md` is synthesized — one per workspace crate
# with a README.md, virtualized under docs/ (mara's ask: "behaves as if
# hive-core/README.md lives at docs/crates/hive-core.md"). The
# crate's own README stays the single source of truth; this derivation
# only projects it into the docs tree, so there is no second copy to keep
# in sync by hand. `docs.nix` (website repo) needs no changes to pick these
# up — it already walks every subdirectory + `.md` file generically.
# The docs/ tree is copied verbatim. Two more subdirs are virtualized on
# top of it, same reasoning for both: project an external source of
# truth into the tree instead of hand-copying (and drifting) it.
# `docs.nix` (website repo) needs no changes to pick either up — it
# already walks every subdirectory generically.
#
# Output layout:
# $out/ — the repo docs/ tree verbatim (e.g. $out/setup.md)
# $out/crates/<crate>.md — one per workspace crate README, plus the
# hand-written docs/crates/README.md
# landing page (copied verbatim like any
# other docs/ file, not generated here)
# $out/ — the repo docs/ tree verbatim
# $out/crates/<crate>.md — one per workspace crate README
# $out/options/*.md — the nixosOptionsDoc bundle (`packages.docs`,
# nix/docs/default.nix), copied verbatim —
# already self-contained CommonMark, unlike
# the crate READMEs below, so no rewriting.
let
cargoToml = builtins.fromTOML (builtins.readFile ../../Cargo.toml);
@ -58,7 +57,7 @@ stdenv.mkDerivation {
# the alternative is hand-copying READMEs into docs/ and letting them
# drift, which is the exact duplication this issue exists to avoid.
src = ../../docs;
inherit self;
inherit self optionsMd;
dontBuild = true;
dontConfigure = true;
@ -68,6 +67,7 @@ stdenv.mkDerivation {
mkdir -p $out
cp -r ./* $out/
mkdir -p "$out/crates"
cp -r "$optionsMd" "$out/options"
${lib.concatMapStrings (member: ''
if [ -f "$self/${member}/README.md" ]; then
@ -94,7 +94,7 @@ stdenv.mkDerivation {
dontFixup = true;
meta = {
description = "hyperhive reference docs (the repo docs/ tree, plus a virtual crates/<crate>.md per workspace crate README)";
description = "hyperhive reference docs (the repo docs/ tree, plus virtual crates/<crate>.md and options/*.md subdirs)";
homepage = "https://forge.darkest.space/hyperhive/hyperhive";
};
}