docs/atlas/generate.jl has two artefact-hygiene bugs, both surfaced while regenerating
for #810 and both pre-existing (neither is caused by that change).
1. It is not idempotent — every run appends a blank line to 11 model pages
Measured on a clean main working tree, no source edits:
$ julia docs/atlas/generate.jl && git diff --stat docs/src/models/
11 files changed, 11 insertions(+) # all of them a single blank line
$ julia docs/atlas/generate.jl && git diff --stat docs/src/models/
11 files changed, 22 insertions(+) # it accumulates
The 11: ising-square, ising-triangular, six-vertex, heisenberg, hubbard1d,
kitaev-honeycomb, kitaev1d, majumdar_ghosh, tfim, toric-code, xxz. These are
the hand-written model pages the generator injects a section into, so the injection is
presumably re-emitting a trailing newline that the surrounding text already supplies.
Consequences: main is permanently "one run behind", every PR that regenerates carries
10 unrelated files of noise, and a reviewer cannot tell a real docs change from the
wobble. In #810 those 10 files had to be reverted by hand to keep the diff legible.
2. It never prunes pages for rows that no longer exist
Deleting a @register row removes the hub from every index (the model page, the quantity
page, the sitemap — all correct), but leaves docs/src/atlas/hubs/<Model>_<Quantity>_<BC>.md
on disk as an unreferenced orphan.
Three orphans exist today:
Detection is one pass over docs/src/atlas/hubs/*.md checking whether each stem appears
anywhere in docs/src/atlas/** outside hubs/.
Why it matters together
The atlas pages are advertised as a pure VIEW over the registry claims. An orphan page is
a hub page for a claim the registry no longer makes — it will still render, still be
reachable by URL, and still assert an assurance badge for a row that is gone. That is the
one failure mode a generated view is supposed to be immune to.
Suggested fix
- Make the model-page injection idempotent (write the section, do not append to it), and
add a test that runs the generator twice and asserts the second run is a no-op — the
property that would have caught this.
- Prune
hubs/ to exactly the set of registered (model, quantity, bc) triples on each
run, and delete the two remaining orphans.
docs/atlas/generate.jlhas two artefact-hygiene bugs, both surfaced while regeneratingfor #810 and both pre-existing (neither is caused by that change).
1. It is not idempotent — every run appends a blank line to 11 model pages
Measured on a clean
mainworking tree, no source edits:The 11:
ising-square,ising-triangular,six-vertex,heisenberg,hubbard1d,kitaev-honeycomb,kitaev1d,majumdar_ghosh,tfim,toric-code,xxz. These arethe hand-written model pages the generator injects a section into, so the injection is
presumably re-emitting a trailing newline that the surrounding text already supplies.
Consequences:
mainis permanently "one run behind", every PR that regenerates carries10 unrelated files of noise, and a reviewer cannot tell a real docs change from the
wobble. In #810 those 10 files had to be reverted by hand to keep the diff legible.
2. It never prunes pages for rows that no longer exist
Deleting a
@registerrow removes the hub from every index (the model page, the quantitypage, the sitemap — all correct), but leaves
docs/src/atlas/hubs/<Model>_<Quantity>_<BC>.mdon disk as an unreferenced orphan.
Three orphans exist today:
Hubbard1D_MassGap_Infinite— from Stop encoding the gap sector twice at Hubbard1D #810; deleted by hand thereHeisenberg1D_ZZStructureFactor_Infinite— olderXXZ1D_ZZStructureFactor_Infinite— olderDetection is one pass over
docs/src/atlas/hubs/*.mdchecking whether each stem appearsanywhere in
docs/src/atlas/**outsidehubs/.Why it matters together
The atlas pages are advertised as a pure VIEW over the registry claims. An orphan page is
a hub page for a claim the registry no longer makes — it will still render, still be
reachable by URL, and still assert an assurance badge for a row that is gone. That is the
one failure mode a generated view is supposed to be immune to.
Suggested fix
add a test that runs the generator twice and asserts the second run is a no-op — the
property that would have caught this.
hubs/to exactly the set of registered(model, quantity, bc)triples on eachrun, and delete the two remaining orphans.