feat: robust docs

src/lib.rs

@@ -26,7 +26,7 @@
 //! ## The loop
 //!
 //! ```text
-//! author items ──▶ validate ──▶ lint ──▶ assemble ──▶ export ───┐
+//! author items ──▶ validate ──▶ lint ──▶ assemble ──▶ export ──┐
 //!      ▲                                                        │
 //!      │                                                   administer
 //!      │                                                        │
@@ -47,29 +47,54 @@
 //! already get right and then drifts from it. [`assessment::History`] derives usage
 //! by scanning the records.
 //!
-//! Fingerprints cover only what a student saw. Retag an item's metadata and its
+//! **Fingerprints cover only what a student saw.** Retag an item's metadata and its
 //! pooled statistics stay valid; reword the stem and they are marked stale. See
 //! [`item::Item::fingerprint`].
 //!
-//! Validation reports everything at once. Fixing one typo per run is not a
+//! **Validation reports everything at once.** Fixing one typo per run is not a
 //! workflow. [`error::Error::Invalid`] carries a list.
 //!
-//! Validation and linting are separate. [`bank::BankFile::validate`] enforces
+//! **Validation and linting are separate.** [`bank::BankFile::validate`] enforces
 //! what must be true; [`lint`] advises on what is usually a mistake, and every rule
 //! has a code you can silence.
 //!
-//! Small samples are labelled as such. Every statistic computed from a class of
+//! **Small samples are labelled as such.** Every statistic computed from a class of
 //! twenty-five is reported with the caveat it deserves rather than three decimal
 //! places of false precision.
+//!
+//! ## Dependency posture
+//!
+//! Deliberately small: serde, a YAML parser, clap, thiserror, and csv, plus arrow
+//! and parquet behind a default-on feature that can be switched off. Dates, PRNG,
+//! hashing, ZIP writing, and the psychometrics are implemented here rather than
+//! pulled in — see [`date`], [`rng`], [`hash`], [`zipfile`], [`irt`]. For a tool
+//! whose job is to still open a course repository in five years, that tradeoff
+//! favours fewer moving parts.
+//!
+//! ## Where to start
+//!
+//! This page describes the shape of the crate. For a walkthrough, [`guide`] holds
+//! setup, authoring, and tutorials, starting with [`guide::setup`].
 
 #![warn(missing_docs)]
 #![forbid(unsafe_code)]
+// A broken link in a tutorial is a silent lie about the API, so it fails the build
+// rather than warning into a log nobody reads.
+#![deny(rustdoc::broken_intra_doc_links)]
+#![warn(rustdoc::invalid_codeblock_attributes)]
+#![warn(rustdoc::invalid_html_tags)]
+#![warn(rustdoc::bare_urls)]
+#![warn(rustdoc::private_intra_doc_links)]
+// Lets `cargo doc` mark feature-gated items with the feature that enables them, on
+// a nightly toolchain or on docs.rs. Ignored elsewhere.
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 pub mod analysis;
 pub mod authoring;
 pub mod data;
 pub mod error;
 pub mod export;
+pub mod guide;
 pub mod model;
 pub mod util;