Skip to content

docs/atlas/generate.jl: not idempotent, and never prunes stale hub pages #811

Description

@sotashimozono

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions