From 5dce46830d11ec1a0360fa7bed7b2c9d1e5df70d Mon Sep 17 00:00:00 2001 From: iris Date: Wed, 2 Sep 2026 02:15:52 +0200 Subject: [PATCH] reference-docs: virtualize the options bundle under docs/options/, like crates/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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/.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. --- nix/packages/default.nix | 13 ++++++++----- nix/packages/reference-docs.nix | 30 +++++++++++++++--------------- 2 files changed, 23 insertions(+), 20 deletions(-) diff --git a/nix/packages/default.nix b/nix/packages/default.nix index 90487908..25b8a848 100644 --- a/nix/packages/default.nix +++ b/nix/packages/default.nix @@ -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. diff --git a/nix/packages/reference-docs.nix b/nix/packages/reference-docs.nix index d8eae450..d44169ed 100644 --- a/nix/packages/reference-docs.nix +++ b/nix/packages/reference-docs.nix @@ -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/.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/.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/.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/.md per workspace crate README)"; + description = "hyperhive reference docs (the repo docs/ tree, plus virtual crates/.md and options/*.md subdirs)"; homepage = "https://forge.darkest.space/hyperhive/hyperhive"; }; }