Generovaná referenční dokumentace je součástí uzavření dokumentace, od zdroje po veřejnou URL

Zdůvodnění

Dokud tento repozitář měl Rust crate, jeho kontrola při každém běhu vykreslila referenční dokumentaci crate a výsledek zahodila. scripts/rust-check spustil RUSTDOCFLAGS='-D warnings' cargo doc --no-deps --quiet, prokázal, že každá exportovaná položka je zdokumentovaná a že se stránky vykreslí bez varování, a stránky nechal tam, kam je cargo zapsal. Žádný webový povrch je nedeklaroval, žádný krok buildu je nenesl, publikační job neměl Rust toolchain, veřejné ověření četlo jediný soubor, který nepoznal, zda tam jsou, a nic nemapovalo položku na stránku, kterou jí rustdoc dává. Když se majitel 2026-09-24 zeptal, kde reference je, každá kandidátní trasa veřejného webu odpověděla 404.

Nic z toho seznamu není vada dokumentace. Každé je fáze za rendererem, kterou nic nevlastnilo, a zelená kontrola byla přečtena — nikým konkrétním, tak se to děje — jako by reference existovala. Kontrola v jedné fázi neříká nic o dalších sedmi. To je obecný tvar, který toto pravidlo odmítá, a vygenerovaná referenční dokumentace je místo, kde jej toto repozitář potkalo: uzávěr je platný, jen když je rozhodnuta každá fáze, a fáze s nejvíce důkazy za sebou bývá zpravidla první.

Druhá polovina je, jak se rozhoduje každá fáze. Reference je velká množina — každá položka, každá stránka, každý odkaz — a svůdný způsob kontroly velké množiny je seznam. Seznam modulů vedený pro kontrolu reference zastará při prvním modulu, který crate získá, a zastará směrem, který projde: nový modul na seznamu není, takže jeho chybějící stránka není nález. Množiny se proto odvozují: položky z vlastního měření crate o sobě, trasy z položek podle konvence toolchainu, mount z deklarace povrchu a to, co publikace nese, z rozřešené topologie.

Požadované chování

Každá fáze uzavření platí a každou rozhoduje něco spustitelného.

1. Zdroj. Každá exportovaná položka je zdokumentována a nese, co od ní žádá project.rust-public-api-quality. Toto pravidlo nepřidává žádný práh: missing_docs s -D warnings a ratchet rust-quality jsou politikou pokrytí.
2. Generování. Jeden producent, scripts/rust-check --doc, spouští stejné volání cargo doc, o kterém kontrola dokazuje, že je bez varování — existuje právě jeden takový řádek — a zapisuje target/web/rustdoc/ s surface.json, který zaznamenává commit, ze kterého byl postaven, a úvodní stránku. Pro publikaci neexistuje druhé volání a soukromé položky knihovny se nedokumentují, protože to, co se publikuje, musí být to, co kontrola dokázala a co ADR 0028 určuje jako veřejné; spustitelný soubor se dokumentuje tak, jak cargo dokumentuje jakýkoli binární cíl.
3. Vložení. Povrch rustdoc je deklarován objevením z crate, v topologii bez ohledu na to, zda producent běžel, připojen na /rustdoc a dostupný běžícímu procesu i publikaci. Commitnutá projekce topologie nenese žádnou hodnotu, která se liší mezi checkouty.
4. Routování. majordomus serve odpovídá na /rustdoc/ ze stromu a publikace nese strom na stejném mountu. Cesta k němu není nikde zapsána kromě své deklarace.
5. Odkazy. Každá exportovaná položka má svou stránku na trase odvozené z její cesty a druhu, žádná stránka položky neexistuje bez své položky, každý vnitřní odkaz stromu se rozliší a odkaz ze stránky webu do /rustdoc/ se rozliší vůči složenému stromu. Stránka webu, která popisuje modul exportovaný crate, odkazuje na stránku tohoto modulu přes stejné trasy modulů, které kontrola odvozuje, a to jen v buildu, který referenci složil.
6. Testy. Každá fáze má případ, který ji rozbije a sleduje odmítnutí. Případ, který nedosáhne svého předmětu, to řekne, místo aby prošel.
7. Nasazení. Publikace se skládá z commitnuté topologie: každý publikovaný statický povrch se zkopíruje na svůj mount, bez řádku, který by pojmenoval tento. Publikovaný povrch, jehož artefakt chybí, odmítne build a pojmenuje svého producenta, a složený povrch sestavený z jiného commitu než build se odmítne dřív, než se cokoli pushne. Strom vzniká v CI a nikdy se necommituje.
8. Ověření nasazení. Jakmile web servíruje nasazený commit, veřejná reference se proti němu ověří: její deklarace a vlastní stránka COMMIT crate jmenují ten commit a index crate odpovídá svou identitou. Nasazení, které tímto neprojde, je neúspěšné nasazení.

Inventáře a trasy pocházejí z kanonických metadat. Inventář položek je quality::source::Inventory, měření syntaktického stromu crate; trasy se z něj odvozují; mount je deklarace povrchu; kompozice je docs/generated/web.json. Seznam modulů, položek, stránek nebo tras napsaný pro jednoho konzumenta je závada bez ohledu na to, zda se aktuálně shoduje, pokud není generovaný a kontrola neodmítá jeho drift.

Generování, které uspělo, není důkazem nasazení. Krok cargo doc zezelenalý říká, že se stránky vykreslují; neříká nic o tom, zda jsou servírovány, složeny, úplné, aktuální nebo veřejné, a žádný report to nesmí prezentovat, jako by říkal.

Chování při selhání

• majordomus quality rustdoc skončí s 10 a jedním nálezem na porušení — položka bez své stránky, stránka bez své položky, strom sestavený z jiného commitu nebo žádný nedeklarující, index crate bez své identity, chybějící aktivum indexu, vnitřní odkaz, který se nevyřeší, strojová cesta nebo tajemství na stránce — každý jmenuje položku či stránku a nápravu. Skončí s 12, když není co posuzovat, což se nikdy nehlásí jako úspěch nad ničím (project.empty-is-not-failure).
• scripts/site-build skončí s 12, když povrch, který topologie publikuje, nemá artefakt, a jmenuje producenta, který jej zapisuje, a s 10, když mount povrchu už zaplňuje samotný web.
• scripts/site-check selže (sekce 13m), když složený povrch v buildu chybí, nenese deklaraci, deklaruje jiné id nebo mount než topologie, nebo byl sestaven z jiného commitu než build, a když to /build.json zaznamenává jinak.
• scripts/ci/link-check skončí s 10 pro odkaz ze stránky webu do /rustdoc/, který se ve složeném stromu nerozliší.
• scripts/pages verify-rustdoc selže, když veřejná reference chybí, je rozbitá nebo postavená z jiného commitu, než který je nasazen. V pages.yml je to tvrdý krok, takže běh nasazení je červený; v scripts/ci/pages-check je to sekce kontroly pages-live, která se zeptá znovu při další plné validaci a při finish.
• majordomus web validate, kontrola web-topology, odmítne topologii, v níž se povrch střetává s jiným nebo je v jiném vnořen.

Kontroly jsou rust-check (jehož krok rustdoc zakazuje varování a produkuje strom), rustdoc (kontrola integrity nad stromem, který ten běh vyprodukoval a který vyžaduje; obě v jobu rust), site-build (kompozice a statické kontroly nad složeným stromem), web-topology a pages-live.

Ověření

test/cases/486_rustdoc_composition.sh až test/cases/490_rustdoc_new_module.sh a test/cases/492_rustdoc_module_links.sh, po jedné fázi:

• 486: složení — build webu nese referenci na svém mountu z topologie a při chybějícím artefaktu odmítne a pojmenuje producenta.
• 487: zastaralost — strom sestavený z jiného commitu odmítne kontrola integrity i veřejné ověření.
• 488: objevitelné a dosažitelné — povrch je v topologii a jejích projekcích bez ohledu na to, zda producent běžel, a obsluhovaný proces odpovídá na /rustdoc/.
• 489: nasazení — složený strom je nasazen na bare remote a publikovaná větev nese referenci sestavenou z commitu, který nasazení jmenuje.
• 490: úplnost — modul přidaný do fixture crate se stane povinnou stránkou bez úpravy seznamu a jeho absence je nález.
• 492: referenced — stránka webu každého vestavěného modulu odkazuje na svou stránku rustdoc právě tehdy, když pro něj kontrola jednu odvodí, odkazovaný soubor je ve složeném stromu a build, jehož topologie referenci nemá, žádnou neodkazuje.

Dvě poloviny v Rustu drží vlastní sady crate: cargo test --manifest-path apps/majordomus-cli/Cargo.toml quality::rustdoc pro kontrolu integrity — čistý strom nemá nález a každý způsob selhání vyprodukuje svůj vlastní — a cargo test --manifest-path apps/majordomus-cli/Cargo.toml web::discover pro deklaraci — přítomnou dřív, než běží producent, nezávislou na checkoutu v commitnuté projekci — a apps/majordomus-cli/tests/http_serve.rs pro strom servírovaný celý přes skutečný socket.

scripts/rust-check, scripts/site-build, scripts/site-check, scripts/ci/link-check, scripts/pages a scripts/ci/pages-check jsou spustitelné fáze, které případy lámou. Rozhodnutí je ADR 0086; provozní dokument je docs/RUSTDOC.md.