rustdoc_json/
lib.rs

1//! Utilities for working with rustdoc JSON.
2//!
3//! # Building
4//!
5//! Use [`rustdoc_json::Builder`][Builder] to build rustdoc JSON. Like this:
6//!
7//! ```no_run
8//! let json_path = rustdoc_json::Builder::default()
9//!     .toolchain("nightly")
10//!     .manifest_path("Cargo.toml")
11//!     .build()
12//!     .unwrap();
13//!
14//! println!("Built and wrote rustdoc JSON to {:?}", &json_path);
15//! ```
16//!
17//! A compilable example can be found
18//! [here](https://github.com/cargo-public-api/cargo-public-api/blob/main/rustdoc-json/examples/build-rustdoc-json.rs)
19
20// deny in CI, only warn here
21#![warn(clippy::all, missing_docs)]
22
23use std::path::PathBuf;
24
25mod builder;
26pub use builder::{Builder, Color, PackageTarget};
27
28/// Represents all errors that can occur when using [`Builder::build()`].
29#[derive(thiserror::Error, Debug)]
30#[non_exhaustive]
31pub enum BuildError {
32    /// You tried to generate rustdoc JSON for a virtual manifest. That does not
33    /// work. You need to point to the manifest of a real package.
34    #[error("Manifest must be for an actual package. `{0:?}` is a virtual manifest")]
35    VirtualManifest(PathBuf),
36
37    /// A general error. Refer to the attached error message for more info.
38    #[error("Failed to build rustdoc JSON: {0}")]
39    General(String),
40
41    /// An error originating from building the rustdoc JSON for a crate.
42    ///
43    /// In this case the user will see the exact errors on stderr, regardless of
44    /// if stderr was printed to the terminal or captured with
45    /// [`Builder::build_with_captured_output()`].
46    #[error("Failed to build rustdoc JSON (see stderr)")]
47    BuildRustdocJsonError,
48
49    /// Occurs when stdout or stderr could not be captured when using
50    /// [`Builder::build_with_captured_output()`]).
51    #[error("Failed to capture output: {0}")]
52    CapturedOutputError(String),
53
54    /// Occurs when a command could not be executed, e.g. because the binary
55    /// that we tried to run did not exist.
56    #[error("Failed to execute: {0}")]
57    CommandExecutionError(String),
58
59    /// An error originating from `cargo-manifest`.
60    #[error(transparent)]
61    CargoManifestError(#[from] cargo_manifest::Error),
62
63    /// An error originating from `cargo_metadata`.
64    #[error(transparent)]
65    CargoMetadataError(#[from] cargo_metadata::Error),
66
67    /// Some kind of IO error occurred.
68    #[error(transparent)]
69    IoError(#[from] std::io::Error),
70}
rustdoc_json/lib.rs

rustdoc_json/
lib.rs
