rustdoc-include

一个实用工具，用于将外部Markdown文件导入到*.rs文件中作为文档注释。

动机

在Rust中，您可以使用#[doc = include_str!("...")]将外部Markdown文件导入到您的文档注释中。然而，当使用此方法导入代码示例时，代码示例中错误的报告位置将不正确。

例如，考虑以下情况

// src/lib.rs
#![doc = include_str!("doc.md")]

# src/doc.md

```rust
invalid_func();
```

running 1 test
test src\lib.rs - (line 4) ... FAILED

failures:

---- src\lib.rs - (line 4) stdout ----
error[E0425]: cannot find function `invalid_func` in this scope
 --> src\lib.rs:5:1
  |
3 | invalid_func();
  | ^^^^^^^^^^^^ not found in this scope

错误位置报告为src/lib.rs:5，而不是src/doc.md:3，IDE跳转功能将无法正常工作。

rustdoc-include通过复制Markdown文件中的文档并将其嵌入到*.rs文件中来解决这个问题。此外，在最初导入文档后，您可以通过再次运行rustdoc-include轻松地将*.rs文件与Markdown文件同步。

安装

您可以使用cargo install来安装此工具。

cargo install rustdoc-include

用法

首先，将以下内容添加到Rust源代码中：// #[include_doc("{filepath}", start)] 和 // #[include_doc("{filepath}", end)]

// #[include_doc("file.md", start)]
// #[include_doc("file.md", end)]
fn main() {}

创建一个Markdown文件，路径与您刚才添加的注释中指定的路径相同。

# Title

this is main function.

使用带有--root选项的rustdoc-include运行，指定包含Rust源代码和Markdown文件的目录路径。

rustdoc-include --root ./

此工具将更新Rust源代码，使其看起来像这样

// #[include_doc("file.md", start)]
/// # Title
///
/// this is main function.
// #[include_doc("file.md", end)]
fn main() {}

此工具将由 // #[include_doc("{filepath}", start)] 和 // #[include_doc("{filepath}", end)] 包围的区域替换为 Markdown 文件的正文。因此，在更新 Markdown 文件后重新运行相同的命令，您可以同步源代码中的文档注释与外部 Markdown 文件。

导入包围项的文档注释

您可以通过编写 // #![include_doc(...)] 而不是 // #[include_doc(...)] 来将外部文件作为包围项的文档注释导入，如下所示

// #![include_doc("file.md", start)]
// #![include_doc("file.md", end)]

使用相对路径

导入的 Markdown 文件的路径也可以相对于源文件指定。

// #[include_doc("../dir/file.md", start)]
// #[include_doc("../dir/file.md", end)]

但是，无法导入由 --root 选项指定的目录之外的文件。

限制导入范围

您可以通过向 // #[include_doc("{filepath}", start)] 和 // #[include_doc("{filepath}", end)] 的 start 和 end 添加参数来限制要导入的范围。

start({line_number})

指定要导入的范围的起始行号。

- line 1
- line 2
- line 3

// #[include_doc("file.md", start(2))]
// #[include_doc("file.md", end)]
fn main() {}

// #[include_doc("file.md", start(2))]
/// - line 2
/// - line 3
// #[include_doc("file.md", end)]
fn main() {}

start("{text}")

通过指定该行的文本来设置要导入的范围的起始行。

end({line_number})

指定要导入的范围的结束行号。

end(-{line_number})

通过指定从末尾开始的行数来指定要导入的范围的结束行。

end("{text}")

通过指定该行的文本来设置要导入的范围的结束行。

许可证

本项目在 Apache-2.0/MIT 许可下双许可。请参阅两个 LICENSE-* 文件以获取详细信息。

贡献

除非您明确表示，否则根据 Apache-2.0 许可证定义的，您有意提交的任何贡献，均应如上所述双重许可，而不附加任何额外条款或条件。