From 46963ebf65f8b83cc037b57f03bf2e34927ba7f3 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 20 Apr 2025 19:42:45 -0700 Subject: [PATCH 1/2] Fix some missing docs This removes the `allow(missing_docs)` and fixes any issues. There's probably more work to be done to improve the API docs. This was just a minor thing I wanted to clean up. --- src/renderer/html_handlebars/hbs_renderer.rs | 2 ++ src/renderer/html_handlebars/mod.rs | 2 -- src/utils/fs.rs | 3 +++ src/utils/mod.rs | 8 +++++++- 4 files changed, 12 insertions(+), 3 deletions(-) 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, From 6e143ce2a108a357e4facaf920d84ba584c14aae Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 20 Apr 2025 19:43:32 -0700 Subject: [PATCH 2/2] Add CI job to check API docs This ensures that `cargo doc` does not generate any warnings. --- .github/workflows/main.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) 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) }}'