Rdocs：代码文档化变得简单

简介

当参与开源项目或内部项目时，创建有效的文档至关重要。作为一名开发者，我经常面临生成和维护全面项目文档的挑战。以下示例展示了我所包含的各种类型的文档

• 展示如何使用应用配置的示例。
• 说明如何使用我的 CLI 的 README 指南。
• 在不同场景中展示如何使用我的库的代码片段。

然而，一个常见问题是确保文档中提供的示例保持准确和最新。如果示例代码发生变化怎么办？如果文档中的代码有错别字怎么办？我们如何确保示例始终反映代码库的当前状态呢？

想象一个工具，它允许您提取代码片段，确保它们不仅可靠，而且可执行。如果您可以轻松地合并已知可工作的代码片段或利用来自像 Rust 这样的语言（使用 Doctest）的经过测试的示例，会怎么样？这个工具就是为了解决这些问题而设计的。

目标

我的目标如下

• 与代码保持一致：确保文档始终与代码库保持一致。
• CI 验证：将验证集成到持续集成中，以确保文档的有效性。
• 用户友好：优先考虑所有利益相关者的易用性。
• 最小依赖：即使没有外部工具依赖，也能确保文档的有效性。

它是如何工作的？

过程从您的项目开始。导航到您希望在文档中包含的部分，并用 // 📖 #START <id:adding_numbers> 包围它。用 // 📖 #END 标记该部分的结束。

例如，在 Rust 中，它应该看起来像这样

//📖 #START <id:adding_numbers>
fn add_numbers(a: i32, b: i32) -> i32 {
    a + b
}
//📖 #END

接下来，导航到您的文档，例如readme.md文件，并在其中开始新节，使用以下代码：<!-- 📖ID -->。此节以以下代码结束：<!-- ID📖 -->。

执行命令rdocs replace [COLLECT-FOLDER] [DOC-FOLDER]后，所有示例都将被收集，并无缝替换文档中相应的内容。

可用命令

• rdocs replace：用于替换内容
• rdocs replace --check：如果您想验证块是否相等，则用于CI示例
• rdocs collect：显示所有块

安装

Cargo安装

cargo install rdocs

GitHub发行版：https://github.com/kaplanelad/rdocs/releases/latest

示例

要了解其工作方式，请访问此处，并查看readme文件中从lib.rs文件中提取的部分。