Snipgrep: 简化代码文档

简介

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

• 展示如何使用应用程序配置的示例。
• 说明如何使用我的命令行界面的README指南。
• 演示在不同场景下如何使用我的库的代码片段。

然而，一个常见问题是如何确保提供的示例在文档中保持准确和最新。如果示例代码更改怎么办？如果文档中的代码有误怎么办？我们如何确保示例始终反映代码库的最新状态？

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

目标

我的目标是

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

它是如何工作的？

过程从您的项目开始。导航到您希望包含在文档中的部分，并用 // <snipgrep id="introduction"> 包围它。用 // </snipgrep> 标记部分的结束。

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

// <snipgrep id="introduction">
fn add_numbers(a: i32, b: i32) -> i32 {
    a + b
}
// </snipgrep>

接下来，导航到您的文档，例如readme.md文件，并从以下代码开始本节：<!-- <snipgrep id="ID"> -->。本节以以下代码结束：// </snipgrep>。

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

可用命令

• snipgrep create-db - 创建本地DB文件，以便您可以通过文件管理片段
• snipgrep run - 收集和注入片段

安装

Cargo安装

cargo install snipgrep

可用命令

• snipgrep create-db - 创建本地DB文件，以便您可以通过文件管理片段
• snipgrep run - 收集和注入片段 GitHub仓库