cargo external-doc

此工具允许您将 Markdown 文件添加到由 rustdoc 生成的 crate 文档中。

rustdoc 生成的文档适用于代码和 API 参考，并不提供添加长篇文档的便捷方式。此工具将解决这个问题，直到 rustlang/cargo#739 被实现。

安装

cargo external-doc 通过 cargo install 安装

$ cargo install cargo-external-doc

用法

将您用 Markdown 编写的文章放在项目的 doc/ 子目录中（参见 nom 以获取示例）。

rustdoc 要求文件以标题开头，例如

% Your title here

现在，运行 cargo build 然后运行 cargo external-doc。此工具将

• 调用 cargo doc
• 测试 doc/ 文件中的代码示例
• 生成与 rustdoc 模板一致的 HTML 文件，并将其放入 target/doc/your_crate

您的其他文档文件可以通过相对 URL 引用它，例如对于 doc/guide.md 文件

cf the [guide](guide.html)

示例

在 nom 中，您可以查看

• doc/ 目录
• 在线参考，其中包含文章链接
• 在 src/lib.rs 中的链接
• 以下解析器编写文章及其源代码

注意事项

此工具是临时解决方案，直到有更好的方法集成到 cargo doc中。

它不支持覆盖值，如目标路径。

它依赖于target/debug/libyourcrate.rlib文件的存在。

它不检查无效链接。

它不可配置。

它满足我对nom的需求，可能不适合您的需求。我欢迎修改想法和补丁，但我更希望看到它在cargo doc中正确实现。