diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2f1f4378..64f4c946 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -98,6 +98,18 @@ jobs: - run: rustup component add clippy - run: cargo clippy --workspace --all-targets --no-deps -- -D warnings + docs: + name: Check API docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install Rust + run: bash ci/install-rust.sh stable x86_64-unknown-linux-gnu + - name: Ensure intradoc links are valid + run: cargo doc --workspace --document-private-items --no-deps + env: + RUSTDOCFLAGS: -D warnings + # The success job is here to consolidate the total success/failure state of # all other jobs. This job is then included in the GitHub branch protection # rule which prevents merges unless all other jobs are passing. This makes @@ -112,6 +124,7 @@ jobs: - aarch64-cross-builds - gui - clippy + - docs runs-on: ubuntu-latest steps: - run: jq --exit-status 'all(.result == "success")' <<< '${{ toJson(needs) }}' diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index 5cd6fcaf..ffe083ad 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -20,10 +20,12 @@ use once_cell::sync::Lazy; use regex::{Captures, Regex}; use serde_json::json; +/// The HTML renderer for mdBook. #[derive(Default)] pub struct HtmlHandlebars; impl HtmlHandlebars { + /// Returns a new instance of [`HtmlHandlebars`]. pub fn new() -> Self { HtmlHandlebars } diff --git a/src/renderer/html_handlebars/mod.rs b/src/renderer/html_handlebars/mod.rs index aa56e4ca..6cbdf588 100644 --- a/src/renderer/html_handlebars/mod.rs +++ b/src/renderer/html_handlebars/mod.rs @@ -1,5 +1,3 @@ -#![allow(missing_docs)] // FIXME: Document this - pub use self::hbs_renderer::HtmlHandlebars; pub use self::static_files::StaticFiles; diff --git a/src/utils/fs.rs b/src/utils/fs.rs index 220bcd8b..4d07f8fc 100644 --- a/src/utils/fs.rs +++ b/src/utils/fs.rs @@ -1,3 +1,5 @@ +//! Filesystem utilities and helpers. + use crate::errors::*; use log::{debug, trace}; use std::fs::{self, File}; @@ -202,6 +204,7 @@ fn copy, Q: AsRef>(from: P, to: Q) -> Result<()> { } } +/// Returns the name of the file used for HTTP 404 "not found" with the `.html` extension. pub fn get_404_output_file(input_404: &Option) -> String { input_404 .as_ref() diff --git a/src/utils/mod.rs b/src/utils/mod.rs index b9174b53..fc8584ee 100644 --- a/src/utils/mod.rs +++ b/src/utils/mod.rs @@ -1,4 +1,4 @@ -#![allow(missing_docs)] // FIXME: Document this +//! Various helpers and utilities. pub mod fs; mod string; @@ -194,6 +194,7 @@ pub fn render_markdown(text: &str, smart_punctuation: bool) -> String { render_markdown_with_path(text, smart_punctuation, None) } +/// Creates a new pulldown-cmark parser of the given text. pub fn new_cmark_parser(text: &str, smart_punctuation: bool) -> Parser<'_> { let mut opts = Options::empty(); opts.insert(Options::ENABLE_TABLES); @@ -207,6 +208,11 @@ pub fn new_cmark_parser(text: &str, smart_punctuation: bool) -> Parser<'_> { Parser::new_ext(text, opts) } +/// Renders markdown to HTML. +/// +/// `path` should only be set if this is being generated for the consolidated +/// print page. It should point to the page being rendered relative to the +/// root of the book. pub fn render_markdown_with_path( text: &str, smart_punctuation: bool,