Co to znamená
Každý vestavěný modul má na webu stránku pod /registry/modules/ a každý modul, který crate exportuje, má stránku v referenci crate pod /rustdoc/. První odkazuje na druhou: provenance stránky modulu jmenuje cestu modulu v crate jako „reference crate“ a odkazuje na stránku, na které jej rustdoc dokumentuje. Modul, kterému rustdoc stránku nedá — deklarovaný pub(crate) nebo soukromý — nelinkuje nic, a build, který referenci neskládal, také nic nelinkuje, takže odkaz na stránce modulu nikdy nevede na stránku, která neexistuje.
Princip
Mapování modulu na jeho stránku rustdoc se rozhoduje jednou, tam, kde se kontroluje reference. quality::rustdoc::module_routes čte inventář syntaktického stromu crate (quality::source::Inventory), ponechá moduly, které crate exportuje, a stránku každého odvodí podle pravidla trasy rustdoc — stejného odvození, kterému majordomus quality rustdoc podřizuje publikovaný strom, kde modul bez stránky je nález missing-page. majordomus generate přenáší tuto odpověď do datové sady registru webu (site/data/registry/registry.json) jako rustdoc u každého vestavěného modulu: povrch, pod nímž je stránka publikována, cesta modulu v crate a stránka v rámci povrchu. Čte se ze zdroje crate, takže datová sada je na každém stroji stejná, ať je strom sestavený, nebo ne.
Šablona site/templates/registry-module.html to spojuje s povrchy, které build složil: scripts/site-build zaznamenává každý z nich s jeho mountem v data/build.json z výběru, který mj_web_composed čte z docs/generated/web.json. Odkaz je mount složeného povrchu a stránka přes get_url, takže build pro jinou základní cestu dál funguje. Šablona neodvozuje žádnou routu a nejmenuje žádný vlastní povrch.
Jak to vidět
scripts/rust-check --doc
majordomus quality rustdoc --format json | jq '.modules[] | select(.path | test("builtin::quality$"))'
jq '.registry.modules[] | select(.id == "quality") | .rustdoc' site/data/registry/registry.json
scripts/site-build && grep -o 'crate reference.*quality/index.html' site/public/registry/modules/quality/index.html
bash test/run.sh 492_rustdoc_module_links
cargo test --manifest-path apps/majordomus-cli/Cargo.toml site::tests quality::rustdocCo nepokrývá
Stránky modulů Cockpitu jsou jiný povrch s vlastním rendererem; toto tvrzení se týká publikovaného webu. Zda je odkazovaná stránka úplná, je rustdoc-complete, a zda je z tohoto commitu, je rustdoc-verified-live. Stránka modulu odkazuje na stránku samotného modulu, ne na stránky jeho položek: ty vypisuje stránka rustdocu.
Proč existuje
Reference crate byla zveřejněna bez cesty z stránek, které popisují tentýž kód. Lákavá oprava je řádek v šabloně, který převede src/capability/builtin/<x>.rs na majordomus_cli/capability/builtin/<x>/index.html, jenže ten řádek je druhým vyjádřením pravidla trasy, které už vlastní kontrola rustdoc. Je také chybný pro každý modul, který crate neexportuje: rustdoc nezapisuje stránku pro modul pub(crate), takže by pravidlo vedlo na 404 z každé stránky modulu, který si crate ponechává pro sebe. test/cases/492_rustdoc_module_links.sh přečte každou stránku modulu skutečného buildu proti vlastní odpovědi kontroly a sestaví znovu bez reference, aby viděl, že každý odkaz zmizel.