From e725215103af56af0a3db02cf324b7b4970759b8 Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Thu, 6 Aug 2015 12:38:48 +0200 Subject: [PATCH] Add rustdoc generated API doc --- Cargo.toml | 5 ++++ book-example/src/SUMMARY.md | 2 +- book-example/src/lib/lib.md | 20 ++++++++++++++ deploy.sh | 8 +++++- src/{main.rs => bin/mdbook.rs} | 0 src/lib.rs | 48 +++++++++++++++++++++++++++++++++- 6 files changed, 80 insertions(+), 3 deletions(-) create mode 100644 book-example/src/lib/lib.md rename src/{main.rs => bin/mdbook.rs} (100%) diff --git a/Cargo.toml b/Cargo.toml index 31524c77..e675839d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,3 +13,8 @@ pulldown-cmark = "*" default = ["output"] debug = [] output = [] + +[[bin]] +doc = false +name = "mdbook" +path = "src/bin/mdbook.rs" diff --git a/book-example/src/SUMMARY.md b/book-example/src/SUMMARY.md index 786d17f4..bceb4eb3 100644 --- a/book-example/src/SUMMARY.md +++ b/book-example/src/SUMMARY.md @@ -10,4 +10,4 @@ - [Theme](format/theme/theme.md) - [index.hbs](format/theme/index-hbs.md) - [Syntax highlighting](format/theme/syntax-highlighting.md) -- [Rust Library]() +- [Rust Library](lib/lib.md) diff --git a/book-example/src/lib/lib.md b/book-example/src/lib/lib.md new file mode 100644 index 00000000..3ac9e670 --- /dev/null +++ b/book-example/src/lib/lib.md @@ -0,0 +1,20 @@ +# Rust Library + +Check here for the [API docs](mdbook/index.html) generated by rustdoc +mdBook is not only a command line tool, it can be used as a crate. You can extend it, +integrate it in current projects. Here is a short example: + +```rust +extern crate mdBook; + +use mdBook::MDBook; + +fn main() { + let book = MDBook::new("my-book") // Path to root + .set_src("src") // Path from root to source directory + .set_dest("book") // Path from root to output directory + .read_config() // Parse book.json file for configuration + + book.build().unwrap(); // Render the book +} +``` diff --git a/deploy.sh b/deploy.sh index e14de08f..53bc472d 100644 --- a/deploy.sh +++ b/deploy.sh @@ -5,10 +5,16 @@ set -o errexit -o nounset rev=$(git rev-parse --short HEAD) +# Run cargo doc +cargo doc + # Run mdbook to generate the book target/debug/mdbook build book-example/ -cd book-example/book +# Copy files from rendered book to doc root +cp book-example/book/* target/doc/ + +cd target/doc git init diff --git a/src/main.rs b/src/bin/mdbook.rs similarity index 100% rename from src/main.rs rename to src/bin/mdbook.rs diff --git a/src/lib.rs b/src/lib.rs index b6834d2f..f8a40be8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,52 @@ +//! # mdBook +//! +//! **mdBook** is similar to Gitbook but implemented in Rust. +//! It offers a command line interface, but can also be used as a regular crate. +//! +//! This is the API doc, but you can find a [less "low-level" documentation here](../index.html) that +//! contains information about the command line tool, format, structure etc. +//! It is also rendered with mdBook to showcase the features and default theme. +//! +//! Some reasons why you would want to use the crate (over the cli): +//! +//! - Integrate mdbook in a current project +//! - Extend the capabilities of mdBook +//! - Do some processing or test before building your book +//! - Write a new Renderer +//! - ... +//! +//! ## Example +//! +//! ``` +//! extern crate mdbook; +//! +//! use mdbook::MDBook; +//! +//! fn main() { +//! let book = MDBook::new("my-book") +//! .set_src("source_dir") +//! .set_dest("output_dir") +//! .read_config() // Reads book.json file for settings +//! +//! book.build().unwrap(); +//! } +//! ``` +//! +//! ## Implementing a new Renderer +//! +//! If you want to create a new renderer for mdBook, the only thing you have to do is to implement +//! the [Renderer trait](renderer/renderer/trait.Renderer.html) +//! +//! And then you can swap in your renderer like this: +//! +//! ```ignore +//! let book = MDBook::new("my-book").set_renderer(your_renderer) +//! ``` + + #[macro_use] pub mod macros; -mod book; +pub mod book; mod parse; pub mod renderer; pub mod theme;