sourcey_rustdoc/lib.rs
1//! Convert nightly rustdoc JSON into a stable `RustdocSpec` snapshot.
2//!
3//! `sourcey-rustdoc` powers the `rustdoc()` source adapter in [sourcey], the
4//! static documentation generator. It is published as a standalone crate so
5//! any tool that wants a stable, versioned representation of a Rust crate's
6//! API surface can consume the same schema sourcey uses internally.
7//!
8//! [sourcey]: https://sourcey.com
9//!
10//! # Pipeline
11//!
12//! The high-level flow is:
13//!
14//! 1. Run nightly rustdoc against a Cargo manifest and capture its JSON
15//! output (use the [`rustdoc-json`](https://crates.io/crates/rustdoc-json)
16//! crate for this step).
17//! 2. Deserialize into [`rustdoc_types::Crate`] using a matching
18//! `rustdoc-types` version.
19//! 3. Walk the crate through [`extract::extract_crate`] to produce a
20//! [`RustdocSpec`] tree: modules, items, signature tokens, intra-doc
21//! link table, extracted doctests, and resolved external-crate
22//! references.
23//! 4. Serialize the spec to JSON for downstream consumers (sourcey's
24//! `rustdoc()` adapter, alternative renderers, semver-checkers, etc.).
25//!
26//! The bundled `sourcey-rustdoc` binary performs all four steps for the
27//! common case. Library callers can drive each step directly.
28//!
29//! # Schema stability
30//!
31//! [`SPEC_VERSION`] is the schema's major version. Consumers should
32//! check `RustdocSpec.version` on load and bail with a clear remedy when
33//! it does not match.
34//!
35//! # Examples
36//!
37//! ```no_run
38//! use sourcey_rustdoc::{
39//! extract::{extract_crate, ExtractOptions},
40//! RustdocSpec, SPEC_VERSION,
41//! };
42//!
43//! fn read_snapshot(path: &str) -> serde_json::Result<RustdocSpec> {
44//! let bytes = std::fs::read(path).expect("snapshot");
45//! let spec: RustdocSpec = serde_json::from_slice(&bytes)?;
46//! assert_eq!(spec.version, SPEC_VERSION, "schema version mismatch");
47//! Ok(spec)
48//! }
49//! ```
50
51pub mod diagnostics;
52pub mod doctest;
53pub mod extract;
54pub mod links;
55pub mod signature;
56pub mod spec;
57
58pub use spec::{RustdocSpec, SOURCEY_RUSTDOC_VERSION, SPEC_VERSION};