3c262b6c1b
The generated landing page's own H1 already said "Crate reference" — the directory name should match. Rename docs/components/ -> docs/crates/ and update the generating derivation (nix/packages/reference-docs.nix), its default.nix caller comment, and docs/README.md's link. Fixes #3193
100 lines
4 KiB
Nix
100 lines
4 KiB
Nix
{
|
|
stdenv,
|
|
lib,
|
|
self,
|
|
}:
|
|
|
|
# The repo `docs/` markdown tree, shipped as a standalone derivation so
|
|
# agents can read the reference docs in-container (added as a claude
|
|
# additional directory by the harness) WITHOUT pulling the branding +
|
|
# 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.
|
|
#
|
|
# 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)
|
|
|
|
let
|
|
cargoToml = builtins.fromTOML (builtins.readFile ../../Cargo.toml);
|
|
members = cargoToml.workspace.members;
|
|
|
|
# A member-name relative link (`../<other-crate>`, no specific file —
|
|
# forge's browser renders that as a directory listing today) becomes a
|
|
# sibling crates/<other-crate>.md link once every crate README
|
|
# lives flat in the same directory. Built once, applied per file below,
|
|
# rather than a fresh `lib.concatMapStrings` per crate's own transform —
|
|
# every crate needs the exact same substitution list (every *other*
|
|
# member), so this only differs on the `member != other` filter.
|
|
siblingLinkFixups =
|
|
member:
|
|
lib.concatMapStrings (
|
|
other:
|
|
lib.optionalString (other != member) ''
|
|
-e 's,\]\(\.\./${other}(/)?\),](./${other}.md),g' \
|
|
''
|
|
) members;
|
|
in
|
|
stdenv.mkDerivation {
|
|
pname = "hyperhive-docs";
|
|
version = "0.1.0";
|
|
# Narrow src (just docs/) keeps the *base tree*'s input hash decoupled
|
|
# from the rest of the workspace — a doc edit only re-hashes this half.
|
|
# The crates/ generation below necessarily widens that: it reads
|
|
# each crate's own README.md via `self`, so this derivation's hash now
|
|
# also tracks the whole repo tree (Nix has no cheaper way to depend on
|
|
# "just these few files" out of a flake `self`). Accepted trade-off —
|
|
# 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;
|
|
|
|
dontBuild = true;
|
|
dontConfigure = true;
|
|
|
|
installPhase = ''
|
|
runHook preInstall
|
|
mkdir -p $out
|
|
cp -r ./* $out/
|
|
mkdir -p "$out/crates"
|
|
|
|
${lib.concatMapStrings (member: ''
|
|
if [ -f "$self/${member}/README.md" ]; then
|
|
# Rewrite relative links that were correct from the crate's own
|
|
# position in the repo tree but aren't once the file is
|
|
# virtually one level under docs/ instead:
|
|
# ../docs/x.md (crate root -> repo docs/) -> ../x.md
|
|
# (crates/ -> docs/ is one directory shallower than
|
|
# <crate>/ -> docs/ was, so the leading docs/ segment drops)
|
|
# ../<sibling-crate> (that crate's own directory, no file)
|
|
# -> ./<sibling-crate>.md, once that sibling also has a
|
|
# crates page every crate README lives flat beside it.
|
|
sed -E \
|
|
-e 's,\]\(\.\./docs/,](../,g' \
|
|
${siblingLinkFixups member} \
|
|
"$self/${member}/README.md" \
|
|
> "$out/crates/${member}.md"
|
|
fi
|
|
'') members}
|
|
|
|
runHook postInstall
|
|
'';
|
|
|
|
dontFixup = true;
|
|
|
|
meta = {
|
|
description = "hyperhive reference docs (the repo docs/ tree, plus a virtual crates/<crate>.md per workspace crate README)";
|
|
homepage = "https://forge.darkest.space/hyperhive/hyperhive";
|
|
};
|
|
}
|