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:

toml [build-dependencies] readme-rustdocifier = "0.1.0"

• Create README.md.
• Create build.rs with following content:

```no_run use std::{env, error::Error, fs, path::PathBuf};

const CRATENAME: &str = "yourcratenamehere";

fn main() -> Result<(), Box> { println!("cargo:rerun-if-changed=README.md"); fs::write( PathBuf::from(env::var("OUTDIR")?).join("README-rustdocified.md"), readmerustdocifier::rustdocify( &fs::readtostring("README.md")?, &env::var("CARGOPKGNAME")?, Some(&env::var("CARGOPKGVERSION")?), Some(CRATE_NAME), )?, )?; Ok(()) } ```

• Add this to start of lib.rs:

```no_run

![doc = includestr!(concat!(env!("OUTDIR"), "/README-rustdocified.md"))]

```

• Run cargo doc and see the generated documentation of your library.

Example README.md

```markdown

foo

A foo library.

Usage

Create [Foo::new].

```

Above README.md is rustdocified to:

```markdown

A foo library.

Usage

Create [Foo::new].

```

Link conversions

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