Co to znamená
https://majordomus.dev/rustdoc/ poskytuje referenci crate tak, jak ji vykreslil rustdoc, ze stejného nasazení jako zbytek webu, a commit, ze kterého byla sestavena, je commit, ze kterého byl sestaven web. Je to čitelné zvenčí: /build.json pojmenuje commit webu a pod surfaces commit, který deklaroval producent každého složeného povrchu. Strom se generuje pro každou publikaci a nikdy se necommituje do repozitáře.
Princip
Job rustdoc workflow pro pages, samostatný job, který deploy job potřebuje, vytvoří strom přes složenou akci .github/actions/rustdoc z nasazovaného commitu a předá jej jako artefakt téhož běhu. Deploy job jej stáhne, scripts/site-build jej složí na /rustdoc z commitnuté topologie, scripts/site-check posoudí složený výstup a scripts/site-deploy pushne site/public do gh-pages přesně jako vždy — cesta nasazení se nezměnila; změnilo se to, co nese.
Strom se necommituje, protože je velký, protože vkládá commit, ze kterého byl postaven, na stránku konstanty COMMIT crate a protože by commitnutá kopie byla zastaralá při každém commitu. Jeho čerstvost se místo toho dokazuje nasazeným commitem.
Jak to vidět
curl -fsS https://majordomus.dev/build.json | jq '{commit, surfaces}'
curl -fsS https://majordomus.dev/rustdoc/ | grep -o '<code>[0-9a-f]\{40\}</code>'
git ls-files target/web/rustdoc | wc -l # 0: never committed
bash test/run.sh 489_rustdoc_deployCo nepokrývá
Případ spustí deploy proti lokálnímu bare remote a přečte publikovanou větev zpět; nesahá na GitHub, jehož vlastní build gh-pages a jeho CDN ověřují rustdoc-verified-live a kontrola pages-live. Zda má každá položka svou stránku, je rustdoc-complete. Lokální scripts/site-deploy publikuje referenci stejným způsobem, pokud byl strom vytvořen z commitu, který se nasazuje — což quality rustdoc a vlastní kontroly webu jinak odmítnou.
Proč existuje
Reference existovala tak dlouho jako crate a nikdo ji nemohl číst: kontrola ji vykreslila a zahodila, publikační úloha neměla toolchain Rustu a každá cesta, kterou čtenář mohl zkusit, vracela 404. Smyslem je ji publikovat; publikovat ji z commitu, který web uvádí, z publikované stránky dělá výpověď o kódu, který běží, nikoli o nějakém dřívějším buildu. test/cases/489_rustdoc_deploy.sh nasadí složený web a přečte referenci a její commit z publikované větve.