Skip to content

Add intra-docs links to docs #1438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ehuss merged 2 commits into from
Jan 13, 2021
Merged

Add intra-docs links to docs #1438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e9b0be7
Add intra-docs links to docs
pierwill Jan 10, 2021
cdea0f6
Add missing parenthesis in doc comment.
ehuss Jan 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions src/book/book.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ fn create_missing(src_dir: &Path, summary: &Summary) -> Result<()> {

/// 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
/// recursively applying a closure to each section to mutate the chapters, using
/// [`for_each_mut()`].
Expand Down Expand Up @@ -160,7 +160,7 @@ pub struct Chapter {
pub sub_items: Vec<BookItem>,
/// The chapter's location, relative to the `SUMMARY.md` file.
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>,
}

Expand All @@ -181,8 +181,8 @@ impl Chapter {
}
}

/// Create a new draft chapter that is not attached to a source markdown file and has
/// thus no content.
/// Create a new draft chapter that is not attached to a source markdown file (and thus
/// has no content).
pub fn new_draft(name: &str, parent_names: Vec<String>) -> Self {
Chapter {
name: name.to_string(),
Expand All @@ -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 {
match self.path {
Some(_) => false,
Expand Down Expand Up @@ -302,8 +302,6 @@ fn load_chapter<P: AsRef<Path>>(
///
/// This struct shouldn't be created directly, instead prefer the
/// [`Book::iter()`] method.
///
/// [`Book::iter()`]: struct.Book.html#method.iter
pub struct BookItems<'a> {
items: VecDeque<&'a BookItem>,
}
Expand Down
2 changes: 1 addition & 1 deletion src/book/init.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
self.config = cfg;
self
Expand Down
18 changes: 9 additions & 9 deletions src/book/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ pub struct MDBook {
pub book: Book,
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>>,
}

Expand Down Expand Up @@ -78,7 +78,7 @@ impl MDBook {
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> {
let root = book_root.into();

Expand All @@ -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>>(
book_root: P,
config: Config,
Expand All @@ -121,7 +121,7 @@ impl MDBook {
}

/// 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)`
///
/// ```no_run
Expand Down Expand Up @@ -180,7 +180,7 @@ impl MDBook {
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<()> {
let mut preprocessed_book = self.book.clone();
let preprocess_ctx = PreprocessorContext::new(
Expand Down Expand Up @@ -219,14 +219,14 @@ impl MDBook {
}

/// You can change the default renderer to another one by using this method.
/// The only requirement is for your renderer to implement the [`Renderer`
/// trait](../renderer/trait.Renderer.html)
/// The only requirement is that your renderer implement the [`Renderer`]
/// trait.
pub fn with_renderer<R: Renderer + 'static>(&mut self, renderer: R) -> &mut Self {
self.renderers.push(Box::new(renderer));
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 {
self.preprocessors.push(Box::new(preprocessor));
self
Expand Down Expand Up @@ -303,7 +303,7 @@ impl MDBook {
/// artefacts.
///
/// 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.
///
/// i.e. If there were only one renderer (in this case, the HTML renderer):
Expand Down
2 changes: 1 addition & 1 deletion src/config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
//!
//! The main entrypoint of the `config` module is the `Config` struct. This acts
//! 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.
//!
//!
Expand Down
4 changes: 2 additions & 2 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,9 +76,9 @@
//! access to the various methods for working with the [`Config`].
//!
//! [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
//! [`Config`]: config/struct.Config.html
//! [`Config`]: config::Config

#![deny(missing_docs)]
#![deny(rust_2018_idioms)]
Expand Down
7 changes: 2 additions & 5 deletions src/renderer/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,9 @@ use toml::Value;
/// provide your own renderer, there are two main renderer implementations that
/// 99% of users will ever use:
///
/// - [HtmlHandlebars] - the built-in HTML renderer
/// - [CmdRenderer] - a generic renderer which shells out to a program to do the
/// - [`HtmlHandlebars`] - the built-in HTML renderer
/// - [`CmdRenderer`] - a generic renderer which shells out to a program to do the
/// actual rendering
///
/// [HtmlHandlebars]: struct.HtmlHandlebars.html
/// [CmdRenderer]: struct.CmdRenderer.html
pub trait Renderer {
/// The `Renderer`'s name.
fn name(&self) -> &str;
Expand Down