cargo-onedoc

📝 从文档注释生成 README.md。

只写一次文档！此软件包提供了一个 Cargo 子命令，可以从您的 Rust 文档注释生成 Markdown 文件。

功能

此工具可以接受一个或多个 Markdown 文件和/或 Rust 源文件，并输出一个 Markdown 文件。

在 Rustdoc Markdown 和 CommonMark 之间转换时，会进行以下更改。

标题

标题级别增加一级。例如 # 变为 ##。例如

//! ## MSRV
//!
//! Currently the minimum supported version is 1.51.0.

将变为

### MSRV

Currently the minimum supported version is 1.51.0.

代码块

裸代码块被定义为 Rust 代码块，例如 ```rust。删除代码块中的前导 # 注释。例如以下文档注释

//! ```
//! # fn main() {
//! println!("Hello, world!");
//! # }
//! ```

将变为

```rust
println!("Hello, world!");
```

文档内链接

文档内链接根据配置中的 links 部分进行转换。例如假设以下配置

[links]
"String" = "https://doc.rust-lang.net.cn/stable/std/string/struct.String.html"

以下文档注释

//! Render the template to a [`String`].

将变为

Render the template to a [`String`](https://doc.rust-lang.net.cn/stable/std/string/struct.String.html).

配置

此工具可以使用 onedoc.toml 文件进行配置。有两个主要部分 doc 和 links。

doc

doc 部分用于指定输入文件和输出文件。 input 字段是要读取的文件列表。 output 字段是要写入的文件。 template 字段是使用的模板文件。以下是从 sheldon 仓库的示例。

[[doc]]
input = [
    "docs/src/Installation.md",
    "docs/src/Getting-started.md",
    "docs/src/Command-line-interface.md",
    "docs/src/Configuration.md",
]
output = "README.md"
template = "docs/README_TEMPLATE.md"

links

links 用于指定文档内链接映射。这是必需的，因为此工具无法确定正确的链接。这只是一个链接文本到 URL 的映射。

[links]
"Display" = "https://doc.rust-lang.net.cn/stable/std/fmt/trait.Display.html"

许可证

本项目根据 MIT 许可证和 Apache 许可证（版本 2.0）的条款进行分发。

请参阅LICENSE-APACHE和LICENSE-MIT获取详细信息。