readme-rustdocifier

一个用于将 README.md rustdoc 化以包含到 lib.rs 中的库。

• 移除顶级标题。
• 将其他标题改为高一级别。
• 将包内部的 docs.rs 链接转换为 rustdoc 格式。
• 不会更改代码块内的任何内容。
• （可选）检查转换后的链接是否具有正确的版本和包名。
• 无 unsafe。
• 无依赖。

用法

• 将此添加到 Cargo.toml

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

• 创建 README.md。
• 创建包含以下内容的 build.rs

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(())
}

• 将以下内容添加到 lib.rs 的开头

#![doc = include_str!(concat!(env!("OUT_DIR"), "/README-rustdocified.md"))]

• 运行 cargo doc 并查看库生成的文档。

以下是一个 README.md 的示例

## foo

A foo library.

### Usage

Create [`Foo::new`].

上面的 README.md 被rustdoc化到

A foo library.

## Usage

Create [`Foo::new`].

以下链接转换

如下格式的行转换为 rustdoc 格式：[...]: https://docs.rs/PACKAGE/...

以下转换被完成

• 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

注释

• (1) 路径末尾可以有一个可选的 /。
• (2) 路径末尾可以有一个可选的 / 或 /index.html。
• /MODULES 和相应的 ::MODULES 可以是空的。

安全性

此crate不使用任何 unsafe 代码。这通过 #![forbid(unsafe_code)] 来强制执行。