From 77fe87e8adc5d4497dd0bb1bec6d6c6c4aad288b Mon Sep 17 00:00:00 2001 From: Michael Bryan Date: Thu, 3 Aug 2017 00:29:28 +0800 Subject: [PATCH] Updated the documentation --- rustfmt.toml | 2 +- src/book/builder.rs | 6 ++ src/book/mod.rs | 28 ++++---- src/lib.rs | 40 +++++------- src/renderer/html_handlebars/hbs_renderer.rs | 69 +++++++++----------- 5 files changed, 71 insertions(+), 74 deletions(-) diff --git a/rustfmt.toml b/rustfmt.toml index 5ac9fa56..27c396ee 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -9,7 +9,7 @@ fn_args_density = "Compressed" enum_trailing_comma = true match_block_trailing_comma = true struct_trailing_comma = "Always" -wrap_comments = true +wrap_comments = false use_try_shorthand = true report_todo = "Always" diff --git a/src/book/builder.rs b/src/book/builder.rs index f84c0274..db56420d 100644 --- a/src/book/builder.rs +++ b/src/book/builder.rs @@ -33,6 +33,12 @@ impl Builder { self } + /// Set the renderer to be used. + pub fn set_renderer(mut self, renderer: Box) -> Self { + self.renderer = Some(renderer); + self + } + pub fn build(self) -> Result { // if no custom config provided, try to read it from disk let cfg = match self.config { diff --git a/src/book/mod.rs b/src/book/mod.rs index 16ef8df6..66b6aa70 100644 --- a/src/book/mod.rs +++ b/src/book/mod.rs @@ -70,7 +70,7 @@ impl MDBook { /// # use mdbook::MDBook; /// # use mdbook::loader::BookItem; /// # #[allow(unused_variables)] - /// # fn run() -> ::errors::Result<()> { + /// # fn run() -> ::mdbook::errors::Result<()> { /// # let book = MDBook::new("mybook")?; /// for item in book.iter() { /// match *item { @@ -90,7 +90,6 @@ impl MDBook { /// # } /// # fn main() { run().unwrap() } /// ``` - pub fn iter(&self) -> BookItems { self.book.iter() } @@ -271,22 +270,27 @@ impl MDBook { } pub fn test(&mut self, library_paths: Vec<&str>) -> Result<()> { - // read in the chapters - self.parse_summary().chain_err(|| "Couldn't parse summary")?; - let library_args: Vec<&str> = (0..library_paths.len()).map(|_| "-L") - .zip(library_paths.into_iter()) - .flat_map(|x| vec![x.0, x.1]) - .collect(); + let library_args: Vec<&str> = (0..library_paths.len()) + .map(|_| "-L") + .zip(library_paths.into_iter()) + .flat_map(|x| vec![x.0, x.1]) + .collect(); + for item in self.iter() { + if let BookItem::Chapter(ref ch) = *item { + let chapter_path = ch.path(); - if let BookItem::Chapter(_, ref ch) = *item { - if ch.path != PathBuf::new() { + if chapter_path == Path::new("") { - let path = self.get_source().join(&ch.path); + let path = self.get_source().join(&chapter_path); println!("[*]: Testing file: {:?}", path); - let output = Command::new("rustdoc").arg(&path).arg("--test").args(&library_args).output()?; + let output = Command::new("rustdoc") + .arg(&path) + .arg("--test") + .args(&library_args) + .output()?; if !output.status.success() { bail!(ErrorKind::Subprocess("Rustdoc returned an error".to_string(), output)); diff --git a/src/lib.rs b/src/lib.rs index 1db6e614..d1da463a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -18,19 +18,17 @@ //! ## Example //! //! ```no_run -//! extern crate mdbook; +//! use mdbook::config::BookConfig; +//! use mdbook::book::Builder; //! -//! use mdbook::MDBook; +//! // configure our book +//! let config = BookConfig::new("my-book").with_source("src"); //! -//! # #[allow(unused_variables)] -//! fn main() { -//! let mut book = MDBook::new("my-book") // Path to root -//! .with_source("src") // Path from root to source directory -//! .with_destination("book") // Path from root to output directory -//! .read_config() // Parse book.toml configuration file -//! .expect("I don't handle configuration file errors, but you should!"); -//! book.build().unwrap(); // Render the book -//! } +//! // then create a book which uses that configuration +//! let mut book = Builder::new("my-book").with_config(config).build().unwrap(); +//! +//! // and finally, render the book as html +//! book.build().unwrap(); //! ``` //! //! ## Implementing a new Renderer @@ -41,17 +39,14 @@ //! And then you can swap in your renderer like this: //! //! ```no_run -//! # extern crate mdbook; -//! # -//! # use mdbook::MDBook; -//! # use mdbook::renderer::HtmlHandlebars; -//! # -//! # #[allow(unused_variables)] -//! # fn main() { -//! # let your_renderer = HtmlHandlebars::new(); -//! # -//! let book = MDBook::new("my-book").set_renderer(Box::new(your_renderer)); -//! # } +//! # #![allow(unused_variables)] +//! use mdbook::renderer::HtmlHandlebars; +//! use mdbook::book::Builder; +//! +//! let your_renderer = HtmlHandlebars::new(); +//! let book = Builder::new("my-book").set_renderer(Box::new(your_renderer)) +//! .build() +//! .unwrap(); //! ``` //! If you make a renderer, you get the book constructed in form of `Vec` and you get //! the book config in a `BookConfig` struct. @@ -91,7 +86,6 @@ extern crate serde_json; extern crate pretty_assertions; extern crate tempdir; -mod parse; mod preprocess; pub mod book; pub mod config; diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index 50621958..7d0a1b49 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -30,55 +30,48 @@ impl HtmlHandlebars { fn render_item(&self, item: &BookItem, mut ctx: RenderItemContext, print_content: &mut String) -> Result<()> { // FIXME: This should be made DRY-er and rely less on mutable state + // deferred because we'll probably need to rewrite it anyway when + // renderers are made more pluggable match *item { - BookItem::Chapter(_, ref ch) | - BookItem::Affix(ref ch) => { - if ch.path != PathBuf::new() { + BookItem::Chapter(ref ch) => { + let mut content = ch.content.clone(); - let path = ctx.book.get_source().join(&ch.path); + // TODO: Port the playpen stuff to not require a file on disk + // content = helpers::playpen::render_playpen(&content, ch.path()); - debug!("[*]: Opening file: {:?}", path); - let mut f = File::open(&path)?; - let mut content: String = String::new(); + content = utils::render_markdown(&content, ctx.book.get_curly_quotes()); + print_content.push_str(&content); - debug!("[*]: Reading file"); - f.read_to_string(&mut content)?; + // Update the context with data for this file - // Parse and expand links - if let Some(p) = path.parent() { - content = preprocess::links::replace_all(&content, p)?; - } + let path = match ch.path().to_str() { + Some(p) => p, + None => bail!("Could not convert path to str"), + }; + ctx.data.insert("path".to_owned(), json!(path)); - content = utils::render_markdown(&content, ctx.book.get_curly_quotes()); - print_content.push_str(&content); + ctx.data.insert("content".to_owned(), json!(content)); + ctx.data.insert("chapter_title".to_owned(), json!(ch.name)); - // Update the context with data for this file - let path = ch.path.to_str().ok_or_else(|| { - io::Error::new(io::ErrorKind::Other, "Could not convert path to str") - })?; + // FIXME: This place needs a `Path` as well + // ctx.data.insert( + // "path_to_root".to_owned(), + // json!(utils::fs::path_to_root(&ch.path)), + // ); - ctx.data.insert("path".to_owned(), json!(path)); - ctx.data.insert("content".to_owned(), json!(content)); - ctx.data.insert("chapter_title".to_owned(), json!(ch.name)); - ctx.data.insert( - "path_to_root".to_owned(), - json!(utils::fs::path_to_root(&ch.path)), - ); + // Render the handlebars template with the data + debug!("[*]: Render template"); + let rendered = ctx.handlebars.render("index", &ctx.data)?; + let rendered = self.post_process(rendered); - // Render the handlebars template with the data - debug!("[*]: Render template"); - let rendered = ctx.handlebars.render("index", &ctx.data)?; - let rendered = self.post_process(rendered); + let filename = Path::new(ch.path()).with_extension("html"); - let filename = Path::new(&ch.path).with_extension("html"); + // Write to file + info!("[*] Creating {:?} ✓", filename.display()); + ctx.book.write_file(filename, &rendered.into_bytes())?; - // Write to file - info!("[*] Creating {:?} ✓", filename.display()); - ctx.book.write_file(filename, &rendered.into_bytes())?; - - if ctx.is_index { - self.render_index(ctx.book, ch, &ctx.destination)?; - } + if ctx.is_index { + self.render_index(ctx.book, ch, &ctx.destination)?; } }, _ => {},