Merge pull request #1438 from pierwill/edit-docs
Add intra-docs links to docs
This commit is contained in:
commit
b1c2e466e7
|
@ -66,7 +66,7 @@ fn create_missing(src_dir: &Path, summary: &Summary) -> Result<()> {
|
||||||
|
|
||||||
/// A dumb tree structure representing a book.
|
/// A dumb tree structure representing a book.
|
||||||
///
|
///
|
||||||
/// For the moment a book is just a collection of `BookItems` which are
|
/// For the moment a book is just a collection of [`BookItems`] which are
|
||||||
/// accessible by either iterating (immutably) over the book with [`iter()`], or
|
/// accessible by either iterating (immutably) over the book with [`iter()`], or
|
||||||
/// recursively applying a closure to each section to mutate the chapters, using
|
/// recursively applying a closure to each section to mutate the chapters, using
|
||||||
/// [`for_each_mut()`].
|
/// [`for_each_mut()`].
|
||||||
|
@ -160,7 +160,7 @@ pub struct Chapter {
|
||||||
pub sub_items: Vec<BookItem>,
|
pub sub_items: Vec<BookItem>,
|
||||||
/// The chapter's location, relative to the `SUMMARY.md` file.
|
/// The chapter's location, relative to the `SUMMARY.md` file.
|
||||||
pub path: Option<PathBuf>,
|
pub path: Option<PathBuf>,
|
||||||
/// An ordered list of the names of each chapter above this one, in the hierarchy.
|
/// An ordered list of the names of each chapter above this one in the hierarchy.
|
||||||
pub parent_names: Vec<String>,
|
pub parent_names: Vec<String>,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -181,8 +181,8 @@ impl Chapter {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Create a new draft chapter that is not attached to a source markdown file and has
|
/// Create a new draft chapter that is not attached to a source markdown file (and thus
|
||||||
/// thus no content.
|
/// has no content).
|
||||||
pub fn new_draft(name: &str, parent_names: Vec<String>) -> Self {
|
pub fn new_draft(name: &str, parent_names: Vec<String>) -> Self {
|
||||||
Chapter {
|
Chapter {
|
||||||
name: name.to_string(),
|
name: name.to_string(),
|
||||||
|
@ -193,7 +193,7 @@ impl Chapter {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Check if the chapter is a draft chapter, meaning it has no path to a source markdown file
|
/// Check if the chapter is a draft chapter, meaning it has no path to a source markdown file.
|
||||||
pub fn is_draft_chapter(&self) -> bool {
|
pub fn is_draft_chapter(&self) -> bool {
|
||||||
match self.path {
|
match self.path {
|
||||||
Some(_) => false,
|
Some(_) => false,
|
||||||
|
@ -302,8 +302,6 @@ fn load_chapter<P: AsRef<Path>>(
|
||||||
///
|
///
|
||||||
/// This struct shouldn't be created directly, instead prefer the
|
/// This struct shouldn't be created directly, instead prefer the
|
||||||
/// [`Book::iter()`] method.
|
/// [`Book::iter()`] method.
|
||||||
///
|
|
||||||
/// [`Book::iter()`]: struct.Book.html#method.iter
|
|
||||||
pub struct BookItems<'a> {
|
pub struct BookItems<'a> {
|
||||||
items: VecDeque<&'a BookItem>,
|
items: VecDeque<&'a BookItem>,
|
||||||
}
|
}
|
||||||
|
|
|
@ -28,7 +28,7 @@ impl BookBuilder {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Set the `Config` to be used.
|
/// Set the [`Config`] to be used.
|
||||||
pub fn with_config(&mut self, cfg: Config) -> &mut BookBuilder {
|
pub fn with_config(&mut self, cfg: Config) -> &mut BookBuilder {
|
||||||
self.config = cfg;
|
self.config = cfg;
|
||||||
self
|
self
|
||||||
|
|
|
@ -40,7 +40,7 @@ pub struct MDBook {
|
||||||
pub book: Book,
|
pub book: Book,
|
||||||
renderers: Vec<Box<dyn Renderer>>,
|
renderers: Vec<Box<dyn Renderer>>,
|
||||||
|
|
||||||
/// List of pre-processors to be run on the book
|
/// List of pre-processors to be run on the book.
|
||||||
preprocessors: Vec<Box<dyn Preprocessor>>,
|
preprocessors: Vec<Box<dyn Preprocessor>>,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -78,7 +78,7 @@ impl MDBook {
|
||||||
MDBook::load_with_config(book_root, config)
|
MDBook::load_with_config(book_root, config)
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Load a book from its root directory using a custom config.
|
/// Load a book from its root directory using a custom `Config`.
|
||||||
pub fn load_with_config<P: Into<PathBuf>>(book_root: P, config: Config) -> Result<MDBook> {
|
pub fn load_with_config<P: Into<PathBuf>>(book_root: P, config: Config) -> Result<MDBook> {
|
||||||
let root = book_root.into();
|
let root = book_root.into();
|
||||||
|
|
||||||
|
@ -97,7 +97,7 @@ impl MDBook {
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Load a book from its root directory using a custom config and a custom summary.
|
/// Load a book from its root directory using a custom `Config` and a custom summary.
|
||||||
pub fn load_with_config_and_summary<P: Into<PathBuf>>(
|
pub fn load_with_config_and_summary<P: Into<PathBuf>>(
|
||||||
book_root: P,
|
book_root: P,
|
||||||
config: Config,
|
config: Config,
|
||||||
|
@ -121,7 +121,7 @@ impl MDBook {
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Returns a flat depth-first iterator over the elements of the book,
|
/// Returns a flat depth-first iterator over the elements of the book,
|
||||||
/// it returns an [BookItem enum](bookitem.html):
|
/// it returns a [`BookItem`] enum:
|
||||||
/// `(section: String, bookitem: &BookItem)`
|
/// `(section: String, bookitem: &BookItem)`
|
||||||
///
|
///
|
||||||
/// ```no_run
|
/// ```no_run
|
||||||
|
@ -180,7 +180,7 @@ impl MDBook {
|
||||||
Ok(())
|
Ok(())
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Run the entire build process for a particular `Renderer`.
|
/// Run the entire build process for a particular [`Renderer`].
|
||||||
pub fn execute_build_process(&self, renderer: &dyn Renderer) -> Result<()> {
|
pub fn execute_build_process(&self, renderer: &dyn Renderer) -> Result<()> {
|
||||||
let mut preprocessed_book = self.book.clone();
|
let mut preprocessed_book = self.book.clone();
|
||||||
let preprocess_ctx = PreprocessorContext::new(
|
let preprocess_ctx = PreprocessorContext::new(
|
||||||
|
@ -219,14 +219,14 @@ impl MDBook {
|
||||||
}
|
}
|
||||||
|
|
||||||
/// You can change the default renderer to another one by using this method.
|
/// You can change the default renderer to another one by using this method.
|
||||||
/// The only requirement is for your renderer to implement the [`Renderer`
|
/// The only requirement is that your renderer implement the [`Renderer`]
|
||||||
/// trait](../renderer/trait.Renderer.html)
|
/// trait.
|
||||||
pub fn with_renderer<R: Renderer + 'static>(&mut self, renderer: R) -> &mut Self {
|
pub fn with_renderer<R: Renderer + 'static>(&mut self, renderer: R) -> &mut Self {
|
||||||
self.renderers.push(Box::new(renderer));
|
self.renderers.push(Box::new(renderer));
|
||||||
self
|
self
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Register a [`Preprocessor`](../preprocess/trait.Preprocessor.html) to be used when rendering the book.
|
/// Register a [`Preprocessor`] to be used when rendering the book.
|
||||||
pub fn with_preprocessor<P: Preprocessor + 'static>(&mut self, preprocessor: P) -> &mut Self {
|
pub fn with_preprocessor<P: Preprocessor + 'static>(&mut self, preprocessor: P) -> &mut Self {
|
||||||
self.preprocessors.push(Box::new(preprocessor));
|
self.preprocessors.push(Box::new(preprocessor));
|
||||||
self
|
self
|
||||||
|
@ -303,7 +303,7 @@ impl MDBook {
|
||||||
/// artefacts.
|
/// artefacts.
|
||||||
///
|
///
|
||||||
/// If there is only 1 renderer, put it in the directory pointed to by the
|
/// If there is only 1 renderer, put it in the directory pointed to by the
|
||||||
/// `build.build_dir` key in `Config`. If there is more than one then the
|
/// `build.build_dir` key in [`Config`]. If there is more than one then the
|
||||||
/// renderer gets its own directory within the main build dir.
|
/// renderer gets its own directory within the main build dir.
|
||||||
///
|
///
|
||||||
/// i.e. If there were only one renderer (in this case, the HTML renderer):
|
/// i.e. If there were only one renderer (in this case, the HTML renderer):
|
||||||
|
|
|
@ -2,7 +2,7 @@
|
||||||
//!
|
//!
|
||||||
//! The main entrypoint of the `config` module is the `Config` struct. This acts
|
//! The main entrypoint of the `config` module is the `Config` struct. This acts
|
||||||
//! essentially as a bag of configuration information, with a couple
|
//! essentially as a bag of configuration information, with a couple
|
||||||
//! pre-determined tables (`BookConfig` and `BuildConfig`) as well as support
|
//! pre-determined tables ([`BookConfig`] and [`BuildConfig`]) as well as support
|
||||||
//! for arbitrary data which is exposed to plugins and alternative backends.
|
//! for arbitrary data which is exposed to plugins and alternative backends.
|
||||||
//!
|
//!
|
||||||
//!
|
//!
|
||||||
|
|
|
@ -76,9 +76,9 @@
|
||||||
//! access to the various methods for working with the [`Config`].
|
//! access to the various methods for working with the [`Config`].
|
||||||
//!
|
//!
|
||||||
//! [user guide]: https://rust-lang.github.io/mdBook/
|
//! [user guide]: https://rust-lang.github.io/mdBook/
|
||||||
//! [`RenderContext`]: renderer/struct.RenderContext.html
|
//! [`RenderContext`]: renderer::RenderContext
|
||||||
//! [relevant chapter]: https://rust-lang.github.io/mdBook/for_developers/backends.html
|
//! [relevant chapter]: https://rust-lang.github.io/mdBook/for_developers/backends.html
|
||||||
//! [`Config`]: config/struct.Config.html
|
//! [`Config`]: config::Config
|
||||||
|
|
||||||
#![deny(missing_docs)]
|
#![deny(missing_docs)]
|
||||||
#![deny(rust_2018_idioms)]
|
#![deny(rust_2018_idioms)]
|
||||||
|
|
|
@ -34,12 +34,9 @@ use toml::Value;
|
||||||
/// provide your own renderer, there are two main renderer implementations that
|
/// provide your own renderer, there are two main renderer implementations that
|
||||||
/// 99% of users will ever use:
|
/// 99% of users will ever use:
|
||||||
///
|
///
|
||||||
/// - [HtmlHandlebars] - the built-in HTML renderer
|
/// - [`HtmlHandlebars`] - the built-in HTML renderer
|
||||||
/// - [CmdRenderer] - a generic renderer which shells out to a program to do the
|
/// - [`CmdRenderer`] - a generic renderer which shells out to a program to do the
|
||||||
/// actual rendering
|
/// actual rendering
|
||||||
///
|
|
||||||
/// [HtmlHandlebars]: struct.HtmlHandlebars.html
|
|
||||||
/// [CmdRenderer]: struct.CmdRenderer.html
|
|
||||||
pub trait Renderer {
|
pub trait Renderer {
|
||||||
/// The `Renderer`'s name.
|
/// The `Renderer`'s name.
|
||||||
fn name(&self) -> &str;
|
fn name(&self) -> &str;
|
||||||
|
|
Loading…
Reference in New Issue