pub fn rustdoc(root: &Path) -> Option<Surface>Expand description
The crate’s rustdoc, when this repository has the crate.
Declared from the source it documents, exactly as the documentation build is declared
from the site’s configuration: the crate existing is what says the reference exists,
and whether cargo doc has run in this checkout decides only whether it is built.
That is what keeps the topology — and the committed projection of it — the same on
every machine; an unbuilt reference is served as a 503 naming RUSTDOC_PRODUCER, and
web validate --artifacts is where its absence becomes a finding.
Both worlds hold it. A running process serves it at a top-level mount of its own, and a publication carries it beside the site under the same path, nested under the application’s root, which is the one nesting the validator allows. The revision is read from the declaration the producer writes beside its output; nothing else is, because every other value is decided here and a second statement of it could only disagree.
use majordomus_cli::web::discover::{rustdoc, RUSTDOC, RUSTDOC_MOUNT};
let dir = tempfile::tempdir().unwrap();
assert!(rustdoc(dir.path()).is_none(), "a repository without the crate documents nothing");
std::fs::create_dir_all(dir.path().join("apps/majordomus-cli/src")).unwrap();
std::fs::write(dir.path().join("apps/majordomus-cli/Cargo.toml"), "").unwrap();
std::fs::write(dir.path().join("apps/majordomus-cli/src/lib.rs"), "//! x\n").unwrap();
let surface = rustdoc(dir.path()).expect("the crate is documented");
assert_eq!(surface.id, RUSTDOC);
assert_eq!(surface.mount.as_str(), RUSTDOC_MOUNT);
// declared before it is built: the producer has not run in this directory
assert!(surface.built_from.is_none());
assert!(surface.availability.is_served() && surface.availability.is_published());