diff --git a/book-example/src/format/config.md b/book-example/src/format/config.md index 8b7bdd00..d1980a21 100644 --- a/book-example/src/format/config.md +++ b/book-example/src/format/config.md @@ -10,8 +10,11 @@ title = "Example book" author = "John Doe" description = "The example book covers examples." +[build] +build-dir = "my-example-book" +create-missing = false + [output.html] -destination = "my-example-book" additional-css = ["custom.css"] ``` @@ -32,8 +35,6 @@ This is general information about your book. - **src:** By default, the source directory is found in the directory named `src` directly under the root folder. But this is configurable with the `src` key in the configuration file. -- **build-dir:** The directory to put the rendered book in. By default this is - `book/` in the book's root directory. **book.toml** ```toml @@ -42,7 +43,24 @@ title = "Example book" authors = ["John Doe", "Jane Doe"] description = "The example book covers examples." src = "my-src" # the source files will be found in `root/my-src` instead of `root/src` +``` + +### Build options + +This controls the build process of your book. + +- **build-dir:** The directory to put the rendered book in. By default this is + `book/` in the book's root directory. +- **create-missing:** By default, any missing files specified in `SUMMARY.md` + will be created when the book is built (i.e. `create-missing = true`). If this + is `false` then the build process will instead exit with an error if any files + do not exist. + +**book.toml** +```toml +[build] build-dir = "build" +create-missing = false ``` ### HTML renderer options @@ -134,4 +152,4 @@ if let Some(baz) = book_config.get_deserialized::>("output.random.baz" } // start the rendering process -``` \ No newline at end of file +``` diff --git a/book-example/src/misc/contributors.md b/book-example/src/misc/contributors.md index de01338e..f0184c15 100644 --- a/book-example/src/misc/contributors.md +++ b/book-example/src/misc/contributors.md @@ -12,3 +12,4 @@ If you have contributed to mdBook and I forgot to add you, don't hesitate to add - [funnkill](https://github.com/funkill) - Fu Gangqiang ([FuGangqiang](https://github.com/FuGangqiang)) - [Michael-F-Bryan](https://github.com/Michael-F-Bryan) +- [Chris Spiegel](https://github.com/cspiegel) diff --git a/src/bin/build.rs b/src/bin/build.rs index f3b595e1..54dffbd1 100644 --- a/src/bin/build.rs +++ b/src/bin/build.rs @@ -14,7 +14,7 @@ pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> { book{n}(Defaults to ./book when omitted)'", ) .arg_from_usage( - "--no-create 'Will not create non-existent files linked from SUMMARY.md'", + "--no-create 'Will not create non-existent files linked from SUMMARY.md (deprecated: use book.toml instead)'", ) .arg_from_usage( "[dir] 'A directory for your book{n}(Defaults to Current Directory \ @@ -28,11 +28,12 @@ pub fn execute(args: &ArgMatches) -> Result<()> { let mut book = MDBook::new(&book_dir).read_config()?; if let Some(dest_dir) = args.value_of("dest-dir") { - book.config.book.build_dir = PathBuf::from(dest_dir); + book.config.build.build_dir = PathBuf::from(dest_dir); } + // This flag is deprecated in favor of being set via `book.toml`. if args.is_present("no-create") { - book.create_missing = false; + book.config.build.create_missing = false; } book.build()?; diff --git a/src/bin/serve.rs b/src/bin/serve.rs index 87099411..ac1ba144 100644 --- a/src/bin/serve.rs +++ b/src/bin/serve.rs @@ -52,7 +52,7 @@ pub fn execute(args: &ArgMatches) -> Result<()> { let mut book = MDBook::new(&book_dir).read_config()?; if let Some(dest_dir) = args.value_of("dest-dir") { - book.config.book.build_dir = PathBuf::from(dest_dir); + book.config.build.build_dir = PathBuf::from(dest_dir); } let port = args.value_of("port").unwrap_or("3000"); diff --git a/src/bin/watch.rs b/src/bin/watch.rs index 39862d18..29772715 100644 --- a/src/bin/watch.rs +++ b/src/bin/watch.rs @@ -30,7 +30,7 @@ pub fn execute(args: &ArgMatches) -> Result<()> { let mut book = MDBook::new(&book_dir).read_config()?; if let Some(dest_dir) = args.value_of("dest-dir") { - book.config.book.build_dir = PathBuf::from(dest_dir); + book.config.build.build_dir = PathBuf::from(dest_dir); } if args.is_present("open") { diff --git a/src/book/mod.rs b/src/book/mod.rs index a22473e5..2993f3df 100644 --- a/src/book/mod.rs +++ b/src/book/mod.rs @@ -23,10 +23,6 @@ pub struct MDBook { renderer: Box, pub livereload: Option, - - /// Should `mdbook build` create files referenced from SUMMARY.md if they - /// don't exist - pub create_missing: bool, } impl MDBook { @@ -71,7 +67,6 @@ impl MDBook { renderer: Box::new(HtmlHandlebars::new()), livereload: None, - create_missing: true, } } @@ -179,7 +174,7 @@ impl MDBook { let path = self.get_source().join(&ch.path); if !path.exists() { - if !self.create_missing { + if !self.config.build.create_missing { return Err( format!("'{}' referenced from SUMMARY.md does not exist.", path.to_string_lossy()).into(), ); @@ -388,7 +383,7 @@ impl MDBook { } pub fn get_destination(&self) -> PathBuf { - self.root.join(&self.config.book.build_dir) + self.root.join(&self.config.build.build_dir) } pub fn get_source(&self) -> PathBuf { diff --git a/src/config.rs b/src/config.rs index fd2ed2f0..d23e7a80 100644 --- a/src/config.rs +++ b/src/config.rs @@ -12,6 +12,7 @@ use errors::*; pub struct Config { /// Metadata about the book. pub book: BookConfig, + pub build: BuildConfig, rest: Table, } @@ -91,7 +92,7 @@ impl Config { get_and_insert!(table, "description" => cfg.book.description); // This complicated chain of and_then's is so we can move - // "output.html.destination" to "book.build_dir" and parse it into a + // "output.html.destination" to "build.build_dir" and parse it into a // PathBuf. let destination: Option = table.get_mut("output") .and_then(|output| output.as_table_mut()) @@ -101,7 +102,7 @@ impl Config { .and_then(|dest| dest.try_into().ok()); if let Some(dest) = destination { - cfg.book.build_dir = dest; + cfg.build.build_dir = dest; } cfg.rest = table; @@ -162,8 +163,10 @@ impl<'de> Deserialize<'de> for Config { warn!("It looks like you are using the legacy book.toml format."); warn!("We'll parse it for now, but you should probably convert to the new format."); warn!("See the mdbook documentation for more details, although as a rule of thumb"); - warn!("just move all top level configuration entries like `title`, `author` and "); - warn!("`description` under a table called `[book]` and it should all work."); + warn!("just move all top level configuration entries like `title`, `author` and"); + warn!("`description` under a table called `[book]`, move the `destination` entry"); + warn!("from `[output.html]`, renamed to `build-dir`, under a table called"); + warn!("`[build]`, and it should all work."); warn!("Documentation: http://rust-lang-nursery.github.io/mdBook/format/config.html"); return Ok(Config::from_legacy(table)); } @@ -171,8 +174,14 @@ impl<'de> Deserialize<'de> for Config { let book: BookConfig = table.remove("book") .and_then(|value| value.try_into().ok()) .unwrap_or_default(); + + let build: BuildConfig = table.remove("build") + .and_then(|value| value.try_into().ok()) + .unwrap_or_default(); + Ok(Config { book: book, + build: build, rest: table, }) } @@ -198,8 +207,6 @@ pub struct BookConfig { pub description: Option, /// Location of the book source relative to the book's root directory. pub src: PathBuf, - /// Where to put built artefacts relative to the book's root directory. - pub build_dir: PathBuf, /// Does this book support more than one language? pub multilingual: bool, } @@ -211,12 +218,31 @@ impl Default for BookConfig { authors: Vec::new(), description: None, src: PathBuf::from("src"), - build_dir: PathBuf::from("book"), multilingual: false, } } } +/// Configuration for the build procedure. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(default, rename_all = "kebab-case")] +pub struct BuildConfig { + /// Where to put built artefacts relative to the book's root directory. + pub build_dir: PathBuf, + /// Should non-existent markdown files specified in `SETTINGS.md` be created + /// if they don't exist? + pub create_missing: bool, +} + +impl Default for BuildConfig { + fn default() -> BuildConfig { + BuildConfig { + build_dir: PathBuf::from("book"), + create_missing: true, + } + } +} + #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)] #[serde(default, rename_all = "kebab-case")] pub struct HtmlConfig { @@ -248,7 +274,10 @@ mod tests { description = "A completely useless book" multilingual = true src = "source" + + [build] build-dir = "outputs" + create-missing = false [output.html] theme = "./themedir" @@ -271,9 +300,12 @@ mod tests { description: Some(String::from("A completely useless book")), multilingual: true, src: PathBuf::from("source"), - build_dir: PathBuf::from("outputs"), ..Default::default() }; + let build_should_be = BuildConfig { + build_dir: PathBuf::from("outputs"), + create_missing: false, + }; let playpen_should_be = Playpen { editable: true, editor: PathBuf::from("ace"), @@ -290,6 +322,7 @@ mod tests { let got = Config::from_str(src).unwrap(); assert_eq!(got.book, book_should_be); + assert_eq!(got.build, build_should_be); assert_eq!(got.html_config().unwrap(), html_should_be); } @@ -366,11 +399,15 @@ mod tests { "Create book from markdown files. Like Gitbook but implemented in Rust", )), authors: vec![String::from("Mathieu David")], - build_dir: PathBuf::from("my-book"), src: PathBuf::from("./source"), ..Default::default() }; + let build_should_be = BuildConfig { + build_dir: PathBuf::from("my-book"), + create_missing: true, + }; + let html_should_be = HtmlConfig { theme: Some(PathBuf::from("my-theme")), curly_quotes: true, @@ -382,6 +419,7 @@ mod tests { let got = Config::from_str(src).unwrap(); assert_eq!(got.book, book_should_be); + assert_eq!(got.build, build_should_be); assert_eq!(got.html_config().unwrap(), html_should_be); } } diff --git a/src/lib.rs b/src/lib.rs index 2cf5e3e7..3991ae95 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -28,7 +28,7 @@ //! //! // tweak the book configuration a bit //! md.config.book.src = PathBuf::from("source"); -//! md.config.book.build_dir = PathBuf::from("book"); +//! md.config.build.build_dir = PathBuf::from("book"); //! //! // Render the book //! md.build().unwrap(); diff --git a/tests/init.rs b/tests/init.rs index 0dff7db3..e35edee6 100644 --- a/tests/init.rs +++ b/tests/init.rs @@ -42,7 +42,7 @@ fn run_mdbook_init_with_custom_book_and_src_locations() { let mut md = MDBook::new(temp.path()); md.config.book.src = PathBuf::from("in"); - md.config.book.build_dir = PathBuf::from("out"); + md.config.build.build_dir = PathBuf::from("out"); md.init().unwrap(); diff --git a/tests/rendered_output.rs b/tests/rendered_output.rs index fa2b155b..f8904bdd 100644 --- a/tests/rendered_output.rs +++ b/tests/rendered_output.rs @@ -2,17 +2,21 @@ extern crate mdbook; #[macro_use] extern crate pretty_assertions; extern crate select; +extern crate tempdir; extern crate walkdir; mod dummy_book; use dummy_book::{assert_contains_strings, DummyBook}; +use std::fs::{File, remove_file}; +use std::io::Write; use std::path::Path; use std::ffi::OsStr; use walkdir::{DirEntry, WalkDir, WalkDirIterator}; use select::document::Document; use select::predicate::{Class, Name, Predicate}; +use tempdir::TempDir; use mdbook::errors::*; use mdbook::utils::fs::file_to_string; use mdbook::MDBook; @@ -227,3 +231,50 @@ fn check_spacers() { doc.find(Class("chapter").descendant(Name("li").and(Class("spacer")))).count(); assert_eq!(num_spacers, should_be); } + +/// Ensure building fails if `create-missing` is false and one of the files does +/// not exist. +#[test] +fn failure_on_missing_file() { + let (md, _temp) = create_missing_setup(Some(false)); + + // On failure, `build()` does not return a specific error, so assume + // any error is a failure due to a missing file. + assert!(md.read_config().unwrap().build().is_err()); +} + +/// Ensure a missing file is created if `create-missing` is true. +#[test] +fn create_missing_file_with_config() { + let (md, temp) = create_missing_setup(Some(true)); + + md.read_config().unwrap().build().unwrap(); + assert!(temp.path().join("src").join("intro.md").exists()); +} + +/// Ensure a missing file is created if `create-missing` is not set (the default +/// is true). +#[test] +fn create_missing_file_without_config() { + let (md, temp) = create_missing_setup(None); + + md.read_config().unwrap().build().unwrap(); + assert!(temp.path().join("src").join("intro.md").exists()); +} + +fn create_missing_setup(create_missing: Option) -> (MDBook, TempDir) { + let temp = DummyBook::new().build().unwrap(); + let md = MDBook::new(temp.path()); + + let mut file = File::create(temp.path().join("book.toml")).unwrap(); + match create_missing { + Some(true) => file.write_all(b"[build]\ncreate-missing = true\n").unwrap(), + Some(false) => file.write_all(b"[build]\ncreate-missing = false\n").unwrap(), + None => (), + } + file.flush().unwrap(); + + remove_file(temp.path().join("src").join("intro.md")).unwrap(); + + (md, temp) +}