doc-sync

一个命令行界面（CLI），用于将 Rust 文档转换为 Markdown 文件，然后再将 Markdown 文件转换回 Rust 文档。如果您想使用合适的 Markdown 编辑器来编辑文档注释或想将您的 crate 组织成类似 Obsidian Canvas 的样子，这个工具将很有用。

doc-sync 目前处于非常早期的阶段，主要是为了我的用例而制作的。因此，它不支持一些功能。有关更多信息，请参阅 限制，但总体而言，预期某些操作可能会引起错误。不过，doc-sync 不应该进行任何破坏性的更改；如果确实如此，请提交 GitHub Issue！（然而，这并不意味着您不应该小心行事，在运行 from-markdown 之前，请先使用 git commit 或 dura capture）

将来，我们计划允许将 doc-sync 作为库使用，但到目前为止，它仅作为可执行文件提供。

安装和用法

cargo install doc-sync

安装后，doc-sync 可执行文件应安装到您的 PATH。请使用 doc-sync --help 和 doc-sync [SUBCOMMAND] --help 获取有关可用选项的信息。

将 Rust 文档转换为 Markdown 文件（默认情况下，它们将被输出到 ./target/doc-sync）

doc-sync to-markdown

将 Markdown 文件转换为 Rust 文档

doc-sync from-markdown

限制

以下是 doc-sync 当前不支持但可能将来会支持的一些情况的不完整列表

• 不要期望内部项目（如结构体字段）得到很好的支持。当我们依赖于 rustdoc 时，很难做到这一点，因为我们必须在 rustdoc JSON 类型与 syn 之间进行转换。当我们停止依赖于 rustdoc 时，应该会解决这个问题
• rustdoc 识别不了的内项，如函数中的函数
• 重复项，如使用 #[cfg] 和 #[cfg(not)] 创建的项。目前，应使用第一个匹配的项，可能按照它们在文件中的出现顺序，但我还没有测试过这一点。
• doc-sync 未能正确处理工作区。它目前手动获取 crate 名称，并假设 target 在当前目录中，但它应该使用 cargo metadata 的输出来确定这些值。
• Rustdoc 代码块，如 ```ignore，在转换为 Markdown 后将显示为纯文本。这可能在停止使用 rustdoc 时得到解决，因为我们需要一种在项上存储数据的方式，但到目前为止，只有正常的 rust 代码块（```）在转换为 Markdown 后才会显示为 rust。

以下是不完整的情况列表，doc-sync 可能永远不会支持这些情况

• 从宏扩展的项。我们必须展开宏以找到它扩展到的项，然后使用 rust-analyzer/rustc 来撤销宏展开以找到文档注释的来源（这可能甚至不可能，我还没有研究过）。

如果你在这份清单上没有遇到任何问题，请在 GitHub 上创建一个 Issue，我会将其添加到清单中，或者为其添加支持！

它是如何工作的

文档注释 -> Markdown (to-markdown)

使用夜间工具链运行 rustdoc，这样我们就可以使用不稳定的 JSON 输出功能。读取并反序列化 JSON 输出。doc-sync 遍历所有 doc-sync 识别的项，并为它们创建 Markdown 文件。

Markdown -> 文档注释 (from-markdown)

读取并反序列化先前生成的 rustdoc JSON 输出。doc-sync 遍历所有 Markdown 文件，并从每个文件中提取 rustdoc ID。它使用此信息从 JSON 输出中获取 rustdoc 项和相关信息。如果文档已更改，它将继续。

此时，它需要更新文件中的文档。如果项对应于文件本身，这很容易；只需使用文档注释解析器在文件属性中查找现有的文档注释（如果没有，则将其插入顶部）。

如果不对应于项，它将启动一个过程，遍历项相对于文件的路径的所有部分。对于每个部分，它使用 rustdoc JSON 输出来获取项类型。使用此信息和 syn，它在文件中解析项。然后，它可以使用 proc_macro2 的 Span API 获取项的源文本。然后，它使用文档注释解析器来查找和替换项中的现有文档注释（或插入新的一个）。

待办事项

• 修复所有 clippy 检测（一些似乎是 wrap-match 引起的，例如 clippy::useless_conversion）
• 删除对 rustdoc 的依赖
  • 我们应该使用 syn，它在将文档注释转换回时会提供更多有用的信息
  • 在 rustdoc 和 syn 类型之间进行转换很混乱
  • rustdoc 也不支持/包含我们可以支持的所有内容
• 库，以便可以从 xtasks 和 build.rs 运行
• 测试
• 配置文件以避免总是需要提供参数