From f51d89ba02cdbc7f053c4745c34c343ea7897503 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 21 Jul 2025 11:37:46 -0700 Subject: [PATCH] Move error types to mdbook-core This moves Result and Error to mdbook-core with the anticipation of using them in user crates. For now, the internal APIs will be using anyhow directly, but the intent is to transition more of these to mdbook-core where it makes sense. --- Cargo.lock | 4 ++++ Cargo.toml | 3 ++- crates/mdbook-core/Cargo.toml | 1 + crates/mdbook-core/src/lib.rs | 5 +++++ examples/nop-preprocessor.rs | 2 +- .../mdbook-remove-emphasis/Cargo.toml | 1 + .../mdbook-remove-emphasis/src/main.rs | 2 +- src/book/book.rs | 2 +- src/book/init.rs | 2 +- src/book/mod.rs | 2 +- src/book/summary.rs | 2 +- src/cmd/build.rs | 2 +- src/cmd/clean.rs | 5 +++-- src/cmd/init.rs | 2 +- src/cmd/serve.rs | 2 +- src/cmd/test.rs | 2 +- src/cmd/watch.rs | 2 +- src/config.rs | 7 +++--- src/front-end/mod.rs | 16 ++++++-------- src/lib.rs | 6 ----- src/preprocess/cmd.rs | 2 +- src/preprocess/index.rs | 2 +- src/preprocess/links.rs | 2 +- src/preprocess/mod.rs | 2 +- src/renderer/html_handlebars/hbs_renderer.rs | 4 ++-- src/renderer/html_handlebars/search.rs | 6 ++--- src/renderer/html_handlebars/static_files.rs | 2 +- src/renderer/markdown_renderer.rs | 2 +- src/renderer/mod.rs | 22 +++++++++---------- src/utils/fs.rs | 2 +- src/utils/mod.rs | 10 ++++----- tests/testsuite/preprocessor.rs | 2 +- tests/testsuite/renderer.rs | 2 +- tests/testsuite/toc.rs | 2 +- 34 files changed, 67 insertions(+), 65 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index b19b6304..732e62a9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1297,6 +1297,9 @@ dependencies = [ [[package]] name = "mdbook-core" version = "0.5.0-alpha.1" +dependencies = [ + "anyhow", +] [[package]] name = "mdbook-preprocessor" @@ -1309,6 +1312,7 @@ dependencies = [ name = "mdbook-remove-emphasis" version = "0.1.0" dependencies = [ + "anyhow", "mdbook", "pulldown-cmark 0.12.2", "pulldown-cmark-to-cmark", diff --git a/Cargo.toml b/Cargo.toml index fef052e1..ee570234 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -21,6 +21,7 @@ repository = "https://github.com/rust-lang/mdBook" rust-version = "1.85.0" # Keep in sync with installation.md and .github/workflows/main.yml [workspace.dependencies] +anyhow = "1.0.98" mdbook-core = { path = "crates/mdbook-core" } [package] @@ -42,7 +43,7 @@ description = "Creates a book from markdown files" rust-version.workspace = true [dependencies] -anyhow = "1.0.71" +anyhow.workspace = true chrono = { version = "0.4.24", default-features = false, features = ["clock"] } clap = { version = "4.3.12", features = ["cargo", "wrap_help"] } clap_complete = "4.3.2" diff --git a/crates/mdbook-core/Cargo.toml b/crates/mdbook-core/Cargo.toml index b8888e9c..301bfe87 100644 --- a/crates/mdbook-core/Cargo.toml +++ b/crates/mdbook-core/Cargo.toml @@ -8,6 +8,7 @@ repository.workspace = true rust-version.workspace = true [dependencies] +anyhow.workspace = true [lints] workspace = true diff --git a/crates/mdbook-core/src/lib.rs b/crates/mdbook-core/src/lib.rs index 152102dd..d7298926 100644 --- a/crates/mdbook-core/src/lib.rs +++ b/crates/mdbook-core/src/lib.rs @@ -5,3 +5,8 @@ /// This is provided as a way for custom preprocessors and renderers to do /// compatibility checks. pub const MDBOOK_VERSION: &str = env!("CARGO_PKG_VERSION"); + +/// The error types used in mdbook. +pub mod errors { + pub use anyhow::{Error, Result}; +} diff --git a/examples/nop-preprocessor.rs b/examples/nop-preprocessor.rs index ae593afc..f85fd820 100644 --- a/examples/nop-preprocessor.rs +++ b/examples/nop-preprocessor.rs @@ -1,9 +1,9 @@ //! A basic example of a preprocessor that does nothing. use crate::nop_lib::Nop; +use anyhow::Error; use clap::{Arg, ArgMatches, Command}; use mdbook::book::Book; -use mdbook::errors::Error; use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext}; use semver::{Version, VersionReq}; use std::io; diff --git a/examples/remove-emphasis/mdbook-remove-emphasis/Cargo.toml b/examples/remove-emphasis/mdbook-remove-emphasis/Cargo.toml index 44f9bdd0..cd3e8c83 100644 --- a/examples/remove-emphasis/mdbook-remove-emphasis/Cargo.toml +++ b/examples/remove-emphasis/mdbook-remove-emphasis/Cargo.toml @@ -4,6 +4,7 @@ version = "0.1.0" edition.workspace = true [dependencies] +anyhow.workspace = true mdbook = { path = "../../.." } pulldown-cmark = { version = "0.12.2", default-features = false } pulldown-cmark-to-cmark = "18.0.0" diff --git a/examples/remove-emphasis/mdbook-remove-emphasis/src/main.rs b/examples/remove-emphasis/mdbook-remove-emphasis/src/main.rs index 6112a692..88f58506 100644 --- a/examples/remove-emphasis/mdbook-remove-emphasis/src/main.rs +++ b/examples/remove-emphasis/mdbook-remove-emphasis/src/main.rs @@ -1,9 +1,9 @@ //! This is a demonstration of an mdBook preprocessor which parses markdown //! and removes any instances of emphasis. +use anyhow::Error; use mdbook::BookItem; use mdbook::book::{Book, Chapter}; -use mdbook::errors::Error; use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext}; use pulldown_cmark::{Event, Parser, Tag, TagEnd}; use std::io; diff --git a/src/book/book.rs b/src/book/book.rs index fe5c3f38..769c503d 100644 --- a/src/book/book.rs +++ b/src/book/book.rs @@ -6,8 +6,8 @@ use std::path::{Path, PathBuf}; use super::summary::{Link, SectionNumber, Summary, SummaryItem, parse_summary}; use crate::config::BuildConfig; -use crate::errors::*; use crate::utils::bracket_escape; +use anyhow::{Context, Result}; use log::debug; use serde::{Deserialize, Serialize}; diff --git a/src/book/init.rs b/src/book/init.rs index faca1d09..b7372e33 100644 --- a/src/book/init.rs +++ b/src/book/init.rs @@ -4,9 +4,9 @@ use std::path::PathBuf; use super::MDBook; use crate::config::Config; -use crate::errors::*; use crate::theme; use crate::utils::fs::write_file; +use anyhow::{Context, Result}; use log::{debug, error, info, trace}; /// A helper for setting up a new book and its directory structure. diff --git a/src/book/mod.rs b/src/book/mod.rs index 7c3f0b4c..117d6ed6 100644 --- a/src/book/mod.rs +++ b/src/book/mod.rs @@ -13,6 +13,7 @@ pub use self::book::{Book, BookItem, BookItems, Chapter, load_book}; pub use self::init::BookBuilder; pub use self::summary::{Link, SectionNumber, Summary, SummaryItem, parse_summary}; +use anyhow::{Context, Error, Result, bail}; use log::{debug, error, info, log_enabled, trace, warn}; use std::ffi::OsString; use std::io::{IsTerminal, Write}; @@ -22,7 +23,6 @@ use tempfile::Builder as TempFileBuilder; use toml::Value; use topological_sort::TopologicalSort; -use crate::errors::*; use crate::preprocess::{ CmdPreprocessor, IndexPreprocessor, LinkPreprocessor, Preprocessor, PreprocessorContext, }; diff --git a/src/book/summary.rs b/src/book/summary.rs index 01d6f5f6..72021842 100644 --- a/src/book/summary.rs +++ b/src/book/summary.rs @@ -1,4 +1,4 @@ -use crate::errors::*; +use anyhow::{Context, Error, Result, bail}; use log::{debug, trace, warn}; use memchr::Memchr; use pulldown_cmark::{DefaultBrokenLinkCallback, Event, HeadingLevel, Tag, TagEnd}; diff --git a/src/cmd/build.rs b/src/cmd/build.rs index 53792e4e..05b0bfd2 100644 --- a/src/cmd/build.rs +++ b/src/cmd/build.rs @@ -1,7 +1,7 @@ use super::command_prelude::*; use crate::{get_book_dir, open}; +use anyhow::Result; use mdbook::MDBook; -use mdbook::errors::Result; use std::path::PathBuf; // Create clap subcommand arguments diff --git a/src/cmd/clean.rs b/src/cmd/clean.rs index ec77537e..5a06bc6f 100644 --- a/src/cmd/clean.rs +++ b/src/cmd/clean.rs @@ -1,6 +1,7 @@ use super::command_prelude::*; use crate::get_book_dir; use anyhow::Context; +use anyhow::Result; use mdbook::MDBook; use std::mem::take; use std::path::PathBuf; @@ -15,7 +16,7 @@ pub fn make_subcommand() -> Command { } // Clean command implementation -pub fn execute(args: &ArgMatches) -> mdbook::errors::Result<()> { +pub fn execute(args: &ArgMatches) -> Result<()> { let book_dir = get_book_dir(args); let book = MDBook::load(book_dir)?; @@ -47,7 +48,7 @@ pub struct Clean { } impl Clean { - fn new(dir: &PathBuf) -> mdbook::errors::Result { + fn new(dir: &PathBuf) -> Result { let mut files = vec![dir.clone()]; let mut children = Vec::new(); let mut num_files_removed = 0; diff --git a/src/cmd/init.rs b/src/cmd/init.rs index b31beee9..ddfeaad4 100644 --- a/src/cmd/init.rs +++ b/src/cmd/init.rs @@ -1,8 +1,8 @@ use crate::get_book_dir; +use anyhow::Result; use clap::{ArgMatches, Command as ClapCommand, arg}; use mdbook::MDBook; use mdbook::config; -use mdbook::errors::Result; use std::io; use std::io::Write; use std::process::Command; diff --git a/src/cmd/serve.rs b/src/cmd/serve.rs index e3a0abdd..85866260 100644 --- a/src/cmd/serve.rs +++ b/src/cmd/serve.rs @@ -2,6 +2,7 @@ use super::command_prelude::*; #[cfg(feature = "watch")] use super::watch; use crate::{get_book_dir, open}; +use anyhow::Result; use axum::Router; use axum::extract::ws::{Message, WebSocket, WebSocketUpgrade}; use axum::routing::get; @@ -9,7 +10,6 @@ use clap::builder::NonEmptyStringValueParser; use futures_util::StreamExt; use futures_util::sink::SinkExt; use mdbook::MDBook; -use mdbook::errors::*; use mdbook::utils::fs::get_404_output_file; use std::net::{SocketAddr, ToSocketAddrs}; use std::path::PathBuf; diff --git a/src/cmd/test.rs b/src/cmd/test.rs index d32410f6..fecbc8b0 100644 --- a/src/cmd/test.rs +++ b/src/cmd/test.rs @@ -1,9 +1,9 @@ use super::command_prelude::*; use crate::get_book_dir; +use anyhow::Result; use clap::ArgAction; use clap::builder::NonEmptyStringValueParser; use mdbook::MDBook; -use mdbook::errors::Result; use std::path::PathBuf; // Create clap subcommand arguments diff --git a/src/cmd/watch.rs b/src/cmd/watch.rs index b20cbd11..8050079e 100644 --- a/src/cmd/watch.rs +++ b/src/cmd/watch.rs @@ -1,7 +1,7 @@ use super::command_prelude::*; use crate::{get_book_dir, open}; +use anyhow::Result; use mdbook::MDBook; -use mdbook::errors::Result; use std::path::{Path, PathBuf}; mod native; diff --git a/src/config.rs b/src/config.rs index ef0f5dfd..394154ae 100644 --- a/src/config.rs +++ b/src/config.rs @@ -9,7 +9,7 @@ //! # Examples //! //! ```rust -//! # use mdbook::errors::*; +//! # use anyhow::Result; //! use std::path::PathBuf; //! use std::str::FromStr; //! use mdbook::Config; @@ -47,6 +47,8 @@ //! # run().unwrap() //! ``` +use crate::utils::{self, toml_ext::TomlExt}; +use anyhow::{Context, Error, Result, bail}; use log::{debug, trace, warn}; use serde::{Deserialize, Deserializer, Serialize, Serializer}; use std::collections::HashMap; @@ -58,9 +60,6 @@ use std::str::FromStr; use toml::Value; use toml::value::Table; -use crate::errors::*; -use crate::utils::{self, toml_ext::TomlExt}; - /// The overall configuration object for MDBook, essentially an in-memory /// representation of `book.toml`. #[derive(Debug, Clone, PartialEq)] diff --git a/src/front-end/mod.rs b/src/front-end/mod.rs index 8fd09fc2..fe7b4a2f 100644 --- a/src/front-end/mod.rs +++ b/src/front-end/mod.rs @@ -1,18 +1,16 @@ #![allow(missing_docs)] -pub mod playground_editor; - -pub mod fonts; - -#[cfg(feature = "search")] -pub mod searcher; - +use anyhow::Result; +use log::warn; use std::fs::File; use std::io::Read; use std::path::{Path, PathBuf}; -use crate::errors::*; -use log::warn; +pub mod fonts; +pub mod playground_editor; +#[cfg(feature = "search")] +pub mod searcher; + pub static INDEX: &[u8] = include_bytes!("templates/index.hbs"); pub static HEAD: &[u8] = include_bytes!("templates/head.hbs"); pub static REDIRECT: &[u8] = include_bytes!("templates/redirect.hbs"); diff --git a/src/lib.rs b/src/lib.rs index 73195279..7abd2e15 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -93,9 +93,3 @@ pub use crate::book::MDBook; pub use crate::config::Config; pub use crate::renderer::Renderer; pub use mdbook_core::MDBOOK_VERSION; - -/// The error types used through out this crate. -pub mod errors { - pub(crate) use anyhow::{Context, bail, ensure}; - pub use anyhow::{Error, Result}; -} diff --git a/src/preprocess/cmd.rs b/src/preprocess/cmd.rs index 149dabda..dfd0681e 100644 --- a/src/preprocess/cmd.rs +++ b/src/preprocess/cmd.rs @@ -1,6 +1,6 @@ use super::{Preprocessor, PreprocessorContext}; use crate::book::Book; -use crate::errors::*; +use anyhow::{Context, Result, bail, ensure}; use log::{debug, trace, warn}; use shlex::Shlex; use std::io::{self, Read, Write}; diff --git a/src/preprocess/index.rs b/src/preprocess/index.rs index 1e58e294..3b2666d7 100644 --- a/src/preprocess/index.rs +++ b/src/preprocess/index.rs @@ -3,7 +3,7 @@ use std::{path::Path, sync::LazyLock}; use super::{Preprocessor, PreprocessorContext}; use crate::book::{Book, BookItem}; -use crate::errors::*; +use anyhow::Result; use log::warn; /// A preprocessor for converting file name `README.md` to `index.md` since diff --git a/src/preprocess/links.rs b/src/preprocess/links.rs index 93eaf813..d431ea20 100644 --- a/src/preprocess/links.rs +++ b/src/preprocess/links.rs @@ -1,8 +1,8 @@ -use crate::errors::*; use crate::utils::{ take_anchored_lines, take_lines, take_rustdoc_include_anchored_lines, take_rustdoc_include_lines, }; +use anyhow::{Context, Result}; use regex::{CaptureMatches, Captures, Regex}; use std::fs; use std::ops::{Bound, Range, RangeBounds, RangeFrom, RangeFull, RangeTo}; diff --git a/src/preprocess/mod.rs b/src/preprocess/mod.rs index df01a3db..98daf94e 100644 --- a/src/preprocess/mod.rs +++ b/src/preprocess/mod.rs @@ -10,7 +10,7 @@ mod links; use crate::book::Book; use crate::config::Config; -use crate::errors::*; +use anyhow::Result; use serde::{Deserialize, Serialize}; use std::cell::RefCell; diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index 98203b60..4bef3cb3 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -1,11 +1,11 @@ use crate::book::{Book, BookItem}; use crate::config::{BookConfig, Code, Config, HtmlConfig, Playground, RustEdition}; -use crate::errors::*; use crate::renderer::html_handlebars::StaticFiles; use crate::renderer::html_handlebars::helpers; use crate::renderer::{RenderContext, Renderer}; use crate::theme::{self, Theme}; use crate::utils; +use crate::utils::fs::get_404_output_file; use std::borrow::Cow; use std::collections::BTreeMap; @@ -14,7 +14,7 @@ use std::fs::{self, File}; use std::path::{Path, PathBuf}; use std::sync::LazyLock; -use crate::utils::fs::get_404_output_file; +use anyhow::{Context, Result, bail}; use handlebars::Handlebars; use log::{debug, info, trace, warn}; use regex::{Captures, Regex}; diff --git a/src/renderer/html_handlebars/search.rs b/src/renderer/html_handlebars/search.rs index ea8ae422..3299257d 100644 --- a/src/renderer/html_handlebars/search.rs +++ b/src/renderer/html_handlebars/search.rs @@ -3,17 +3,17 @@ use std::collections::{HashMap, HashSet}; use std::path::{Path, PathBuf}; use std::sync::LazyLock; +use anyhow::{Context, Result, bail}; use elasticlunr::{Index, IndexBuilder}; +use log::{debug, warn}; use pulldown_cmark::*; +use serde::Serialize; use crate::book::{Book, BookItem, Chapter}; use crate::config::{Search, SearchChapterSettings}; -use crate::errors::*; use crate::renderer::html_handlebars::StaticFiles; use crate::theme::searcher; use crate::utils; -use log::{debug, warn}; -use serde::Serialize; const MAX_WORD_LENGTH_TO_INDEX: usize = 80; diff --git a/src/renderer/html_handlebars/static_files.rs b/src/renderer/html_handlebars/static_files.rs index a3cd1322..1b6aa9f7 100644 --- a/src/renderer/html_handlebars/static_files.rs +++ b/src/renderer/html_handlebars/static_files.rs @@ -1,9 +1,9 @@ //! Support for writing static files. +use anyhow::{Context, Result}; use log::{debug, warn}; use crate::config::HtmlConfig; -use crate::errors::*; use crate::renderer::html_handlebars::helpers::resources::ResourceHelper; use crate::theme::{self, Theme, playground_editor}; use crate::utils; diff --git a/src/renderer/markdown_renderer.rs b/src/renderer/markdown_renderer.rs index 4a5a5c2a..ac80aaa2 100644 --- a/src/renderer/markdown_renderer.rs +++ b/src/renderer/markdown_renderer.rs @@ -1,7 +1,7 @@ use crate::book::BookItem; -use crate::errors::*; use crate::renderer::{RenderContext, Renderer}; use crate::utils; +use anyhow::{Context, Result}; use log::trace; use std::fs; diff --git a/src/renderer/mod.rs b/src/renderer/mod.rs index 1c97f8f2..b06983d2 100644 --- a/src/renderer/mod.rs +++ b/src/renderer/mod.rs @@ -11,26 +11,24 @@ //! [For Developers]: https://rust-lang.github.io/mdBook/for_developers/index.html //! [RenderContext]: struct.RenderContext.html -pub use self::html_handlebars::HtmlHandlebars; -pub use self::markdown_renderer::MarkdownRenderer; - -mod html_handlebars; -mod markdown_renderer; - +use crate::book::Book; +use crate::config::Config; +use anyhow::{Context, Result, bail}; +use log::{error, info, trace, warn}; +use serde::{Deserialize, Serialize}; use shlex::Shlex; use std::collections::HashMap; use std::fs; use std::io::{self, ErrorKind, Read}; use std::path::{Path, PathBuf}; use std::process::{Command, Stdio}; - -use crate::book::Book; -use crate::config::Config; -use crate::errors::*; -use log::{error, info, trace, warn}; use toml::Value; -use serde::{Deserialize, Serialize}; +pub use self::html_handlebars::HtmlHandlebars; +pub use self::markdown_renderer::MarkdownRenderer; + +mod html_handlebars; +mod markdown_renderer; /// An arbitrary `mdbook` backend. /// diff --git a/src/utils/fs.rs b/src/utils/fs.rs index 4d07f8fc..3d126b7a 100644 --- a/src/utils/fs.rs +++ b/src/utils/fs.rs @@ -1,6 +1,6 @@ //! Filesystem utilities and helpers. -use crate::errors::*; +use anyhow::{Context, Result}; use log::{debug, trace}; use std::fs::{self, File}; use std::io::Write; diff --git a/src/utils/mod.rs b/src/utils/mod.rs index 14fdd0ad..50feb025 100644 --- a/src/utils/mod.rs +++ b/src/utils/mod.rs @@ -1,19 +1,19 @@ //! Various helpers and utilities. -pub mod fs; -mod string; -pub(crate) mod toml_ext; -use crate::errors::Error; +use anyhow::Error; use log::error; use pulldown_cmark::{CodeBlockKind, CowStr, Event, Options, Parser, Tag, TagEnd, html}; use regex::Regex; - use std::borrow::Cow; use std::collections::HashMap; use std::fmt::Write; use std::path::Path; use std::sync::LazyLock; +pub mod fs; +mod string; +pub(crate) mod toml_ext; + pub use self::string::{ take_anchored_lines, take_lines, take_rustdoc_include_anchored_lines, take_rustdoc_include_lines, diff --git a/tests/testsuite/preprocessor.rs b/tests/testsuite/preprocessor.rs index db8322af..b2188db1 100644 --- a/tests/testsuite/preprocessor.rs +++ b/tests/testsuite/preprocessor.rs @@ -1,8 +1,8 @@ //! Tests for custom preprocessors. use crate::prelude::*; +use anyhow::Result; use mdbook::book::Book; -use mdbook::errors::Result; use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext}; use std::sync::{Arc, Mutex}; diff --git a/tests/testsuite/renderer.rs b/tests/testsuite/renderer.rs index 1e162447..45739d09 100644 --- a/tests/testsuite/renderer.rs +++ b/tests/testsuite/renderer.rs @@ -1,7 +1,7 @@ //! Tests for custom renderers. use crate::prelude::*; -use mdbook::errors::Result; +use anyhow::Result; use mdbook::renderer::{RenderContext, Renderer}; use snapbox::IntoData; use std::fs::File; diff --git a/tests/testsuite/toc.rs b/tests/testsuite/toc.rs index eafbdc48..35b5e5ab 100644 --- a/tests/testsuite/toc.rs +++ b/tests/testsuite/toc.rs @@ -2,7 +2,7 @@ use crate::prelude::*; use anyhow::Context; -use mdbook::errors::*; +use anyhow::Result; use select::document::Document; use select::predicate::{Attr, Class, Name, Predicate}; use std::fs;