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

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

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