#documentation #build #build-dependencies #readme

build readme-rustdocifier

A library for rustdocifying README.md for inclusion in lib.rs

2 releases

0.1.1 Feb 17, 2022
0.1.0 Jan 1, 2022

#246 in Build Utils

Download history 398/week @ 2023-11-20 437/week @ 2023-11-27 432/week @ 2023-12-04 394/week @ 2023-12-11 314/week @ 2023-12-18 247/week @ 2023-12-25 343/week @ 2024-01-01 265/week @ 2024-01-08 344/week @ 2024-01-15 403/week @ 2024-01-22 395/week @ 2024-01-29 656/week @ 2024-02-05 367/week @ 2024-02-12 436/week @ 2024-02-19 765/week @ 2024-02-26 758/week @ 2024-03-04

2,406 downloads per month
Used in 17 crates (10 directly)

MIT license

33KB
746 lines

readme-rustdocifier

A library for rustdocifying README.md for inclusion in lib.rs.

  • Removes top-level header.
  • Changes other headers to be one level higher.
  • Converts package-internal docs.rs links to rustdoc format.
  • Doesn't change anything within code blocks.
  • (optional) Checks that converted links have correct version and crate name.
  • No unsafe.
  • No dependencies.

Usage

  • Add this to Cargo.toml:
[build-dependencies]
readme-rustdocifier = "0.1.0"
  • Create README.md.
  • Create build.rs with following content:
use std::{env, error::Error, fs, path::PathBuf};

const CRATE_NAME: &str = "your_crate_name_here";

fn main() -> Result<(), Box<dyn Error>> {
    println!("cargo:rerun-if-changed=README.md");
    fs::write(
        PathBuf::from(env::var("OUT_DIR")?).join("README-rustdocified.md"),
        readme_rustdocifier::rustdocify(
            &fs::read_to_string("README.md")?,
            &env::var("CARGO_PKG_NAME")?,
            Some(&env::var("CARGO_PKG_VERSION")?),
            Some(CRATE_NAME),
        )?,
    )?;
    Ok(())
}
  • Add this to start of lib.rs:
#![doc = include_str!(concat!(env!("OUT_DIR"), "/README-rustdocified.md"))]
  • Run cargo doc and see the generated documentation of your library.

Example README.md

## foo

A foo library.

### Usage

Create [`Foo::new`].


Above README.md is rustdocified to:


A foo library.

## Usage

Create [`Foo::new`].


Lines like [...]: https://docs.rs/PACKAGE/... are converted to rustdoc format.

Following conversions are done:

  • https://docs.rs/PACKAGE (1)
    • crate
  • https://docs.rs/PACKAGE#fragment (1)
    • crate#fragment
  • https://docs.rs/PACKAGE/VERSION (2)
    • crate
  • https://docs.rs/PACKAGE/VERSION#fragment (2)
    • crate#fragment
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES (2)
    • crate::MODULES
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES#fragment (2)
    • crate::MODULES#fragment
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/enum.ENUM.html
    • crate::MODULES::ENUM
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/enum.ENUM.html#method.METHOD
    • crate::MODULES::ENUM::METHOD
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/enum.ENUM.html#variant.VARIANT
    • crate::MODULES::ENUM::VARIANT
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/enum.ENUM.html#fragment
    • crate::MODULES::ENUM#fragment
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/fn.FUNCTION.html
    • crate::MODULES::FUNCTION
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/fn.FUNCTION.html#fragment
    • crate::MODULES::FUNCTION#fragment
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/macro.MACRO.html
    • crate::MODULES::MACRO
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/macro.MACRO.html#fragment
    • crate::MODULES::MACRO#fragment
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/struct.STRUCT.html
    • crate::MODULES::STRUCT
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/struct.STRUCT.html#method.METHOD
    • crate::MODULES::STRUCT::METHOD
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/struct.STRUCT.html#fragment
    • crate::MODULES::STRUCT#fragment
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/trait.TRAIT.html
    • crate::MODULES::TRAIT
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/trait.TRAIT.html#tymethod.METHOD
    • crate::MODULES::TRAIT::METHOD
  • https://docs.rs/PACKAGE/VERSION/CRATE/MODULES/trait.TRAIT.html#fragment
    • crate::MODULES::TRAIT#fragment

Notes:

  • (1) Can have optional / at path end.
  • (2) Can have optional / or /index.html at path end.
  • /MODULES and corresponding ::MODULES can be empty.

Safety

This crate doesn't use any unsafe code. This is enforced by #![forbid(unsafe_code)].

No runtime deps