cargo-doc2readme

cargo doc2readme 是一个 cargo 子命令，用于创建一个 readme 文件，可在 GitHub 或 crates.io 上显示，其中包含你的代码中的 rustdoc 注释。

安装

如果你使用 ArchLinux，可以从 AUR 安装 cargo-doc2readme

yay -S cargo-doc2readme

在其他操作系统上，确保你已经安装了 Rust（使用你的发行版软件包管理器，但如果你的软件包管理器很糟糕或者你在使用 Windows，请尝试 rustup）然后运行以下命令

cargo install cargo-doc2readme

用法

要生成你的 readme，只需运行

cargo doc2readme

这将输出一个名为 README.md 的文件，使用 README.j2 或内置模板。

如果你想使用 GitHub Actions 运行此命令，可以使用预构建的 docker 镜像

readme:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - uses: docker://ghcr.io/msrd0/cargo-doc2readme
      with:
        entrypoint: cargo
        args: doc2readme --check

这将使用当 cargo doc2readme 最新版本创建时可用的新版稳定 Rust 版本。如果你需要更新的/nightly Rust 编译器，请使用 ghcr.io/msrd0/cargo-doc2readme:nightly docker 镜像。

特性

• 从你的 rustdoc 注释中解析 Markdown 并将其嵌入到 readme 中
• 使用现有的 crates 解析 Rust 和 Markdown
• 支持您的 [CustomType] rustdoc 链接
• 默认的、简约的 README 模板，包含一些有用的徽章
• 自定义 README 模板

非目标

• Markdown 的逐字复制
• 生成的 Markdown 源代码易于阅读

类似工具

cargo readme 是一个类似工具。然而，它带有自己的 Rust 代码解析器，仅覆盖 95% 的用例。此外，它不支持 Rust 1.48 中引入的 Rust 路径链接，这使得您的 README 丑陋，因为 GitHub 将不受支持的链接显示为原始 Markdown，并且对读者来说不太方便，因为读者必须搜索 docs.rs 而不是点击链接。

稳定性保证

此项目遵循语义版本控制。所有版本都将与发布时的最新稳定版 Rust 进行测试。对 rustdoc 输入处理和 Markdown 输出或默认 README 模板的任何非修复错误更改，以及任何与命令行参数或这些稳定性保证不兼容的更改，都被视为破坏性更改。所有其他更改，包括 Rust 代码的任何更改或 MSRV 的提升，都不被视为破坏性更改。