Merge pull request #1438 from pierwill/edit-docs

Add intra-docs links to docs
This commit is contained in:
Eric Huss 2021-01-13 14:26:44 -08:00 committed by GitHub
commit b1c2e466e7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 20 additions and 25 deletions

View File

@ -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>,
} }

View File

@ -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

View File

@ -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):

View File

@ -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.
//! //!
//! //!

View File

@ -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)]

View File

@ -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;