Build webu složí každý publikovaný statický povrch do svého výstupu na jeho přípojném bodě, načtený z commitnuté topologie bez ručně pojmenovaného povrchu, a odmítne build s uvedením producenta, pokud artefakt publikovaného povrchu chybí

Co to znamená

Publikovaný web je víc než to, co vykreslí Zola. Každý statický povrch, který topologie publikuje, jiný než web sám, se zkopíruje do buildu na vlastní mount — dnes je to rustdoc crate na /rustdoc — a nic v buildu nejmenuje, které povrchy to jsou. Povrch přidaný do topologie zítra je složen zítra. Povrch, který topologie publikuje a jehož producent neběžel, build odmítne, jmenuje producenta a nepublikuje nic, protože web, který tiše ztratil povrch, je zastaralé nasazení, které nikdo nevidí.

Princip

scripts/site-build se ptá mj_web_composed v lib/common.sh na složené povrchy: každý povrch docs/generated/web.json druhu statický adresář, který publikovaný web nese, jiný než aplikace. Ptá se dřív, než se vynaloží jakákoli generace nebo vykreslování, a končí s 12 se jmenováním povrchu, jeho mountu, artefaktu a producenta, když artefakt chybí. Poté, co Zola zapsala svůj výstup a proběhl přístupnostní průchod webu, zkopíruje každý artefakt na jeho mount. Mount, který web sám už zaplnil, je odmítnut s exit 10, a ne přepsán, protože jedna cesta má jednoho vlastníka a to, který z nich čtenář dostal, by jinak záviselo na pořadí dvou řádků.

Tentýž výběr říká každé kontrole, které stránky jsou vlastní stránky webu a které patří složenému povrchu, takže smlouva stránek webu posuzuje stránky webu a majordomus quality rustdoc posuzuje stránky reference. Sestavení také zapisuje každý složený povrch s commitem, který deklaroval jeho producent, do /build.json.

Jak to vidět

jq -r '.surfaces[] | select(.kind == "static-directory")
       | [.id, .mount, .availability] | @tsv' docs/generated/web.json
scripts/site-build               # refuses, naming the producer, until the reference exists
scripts/rust-check --doc         # the producer
scripts/site-build               # "== compose rustdoc at /rustdoc", then the route count
jq .surfaces site/data/build.json
bash test/run.sh 486_rustdoc_composition

Co nepokrývá

Zda je složený strom úplný, aktuální a bez rozbitých odkazů, rozhoduje vlastní kontrola povrchu a scripts/site-check nad složeným výstupem, ne sestavení. Publikování složeného stromu je rustdoc-published. Servírované sestavení dokumentace na /docs se skládá stejně a nic zde nenutí běžící server číst site/public.

Proč existuje

Alternativou je krok kopírování na povrch, což je registrace, kterou ADR 0013 odmítlo: správná v den zápisu a špatná ve chvíli, kdy se povrch přidá nebo přejmenuje bez ní. Čtení commitnuté topologie znamená, že publikace nese přesně to, co topologie říká, že publikuje, a odmítnutí znamená, že jediný způsob, jak publikovat bez povrchu, je odebrat jej z topologie, což je viditelná změna. test/cases/486_rustdoc_composition.sh se sestaví bez artefaktu i s ním.