Snipdoc

管理包含代码片段的文档

Snipdoc 是一个简单易用的工具，用于管理包含代码片段的文档。它从您的代码或 YAML 文件中收集代码片段，并将它们注入到文档的各个部分，使文档过程更加高效。

安装

要安装 Snipdoc，您可以使用 Cargo

cargo install snipdoc

或从 GitHub 仓库 下载。

入门

要收集和替换来自多个数据源的所有代码片段，请使用

snipdoc run

有关其工作原理的详细指南，请参阅此 指南

注入选项

Snipdoc 提供了几个属性来自定义代码片段注入

为代码片段添加前缀

add_prefix 属性允许您在每个代码片段的每一行前面添加指定的字符串。这在您需要使用特定前缀格式化注入的代码片段时很有用，例如为代码块中的注释添加前缀。

查看此示例

从代码片段中移除前缀

strip_prefix 属性允许您从代码片段每一行的开头移除指定的字符串。这在您需要通过删除注释前缀或其他不需要的字符来格式化注入的代码片段时很有用。

查看此示例

使用模板

template 属性允许您使用给定的模板包装您的代码片段。这在您有一个希望以特定方式格式化的代码片段时很有用，例如将其用 YAML 标签格式包装。

查看此示例

执行代码片段内容

注意：出于安全原因，此功能默认关闭。要启用它，请使用带有 exec 特性的 Snipdoc 进行编译： cargo install snipdoc --features exec。

执行操作选项 execute 允许您将代码片段作为 shell 命令运行，并将输出收集到代码片段中。这有助于将 --help 命令的结果添加到您的文档中，确保即使 CLI 工具的输出发生变化，文档也能保持最新。

在执行代码片段命令之前，您将需要批准。这允许您在执行之前审查和批准命令。

要跳过批准提示，请设置环境变量 SNIPDOC_SKIP_EXEC_COMMANDS=true。

查看此示例

管理代码片段

要有效地管理所有代码片段，请运行

snipdoc show

创建 YAML 文件

您可以将代码中的代码片段与 YAML 文件配置混合。通过运行创建一个空的 snipdoc.yml 文件：

通过运行以下命令创建一个 snipdoc.yml 文件：

snipdoc create-db --empty

检查代码片段

验证所有代码片段是否有效且与当前注入的版本匹配。这对于 CI 工作流非常有用，可以确保文档的准确性和一致性。

snipdoc check

GitHub Action

要将 Snipdoc 与 GitHub Actions 集成，请使用以下工作流程配置：

name: docs

jobs:
  check:
    name: Check
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout the code
        uses: actions/checkout@v4
      - uses: actions-rs/toolchain@v1
        with:
          profile: minimal
          toolchain: stable
          override: true
      - run: cargo install snipdoc        
      - run: snipdoc check