2023-06: OpenDAL 的文档即代码实践
💡
原文中文，约2800字，阅读约需7分钟。
📝
内容提要
OpenDAL 将用户文档和 API 文档合并到代码中，解决了维护麻烦、互相引用困难、无法版本化等问题，并介绍了实践文档即代码的一些实用小技巧。如果项目的用户文档和 API 文档的读者群完全重叠，可以尝试这种方案，解决文档分裂的体验问题。
🎯
关键要点
- OpenDAL 将用户文档和 API 文档合并到代码中，解决了维护麻烦、互相引用困难、无法版本化等问题。
- OpenDAL 是一个使用 Rust 开发的数据访问库，用户文档和 API 文档通过不同路径提供服务。
- 维护文档需要分别使用 cargo doc 和 mdbook，增加了构建的复杂性。
- API 文档和用户文档分开构建，互相引用困难，导致引用失效。
- mdbook 不支持版本化，用户无法查看旧版本文档。
- 将文档放入代码中，使用 rustdoc 统一构建，简化了构建过程。
- 文档中可以方便引用项目元素，rustdoc 提供 broken intradoc 检查。
- 所有推送到 Crates.io 的包自动构建文档并发布到 Docs.rs，支持版本化。
- 适合将文档视为代码的项目需确保用户文档和 API 文档的读者群重叠。
- 在项目中增加 docs feature 开关来控制文档编译，避免影响编译速度。
- 可以通过 #[doc = include_str!("xxx.md")] 导入本地 Markdown 文件。
- rustdoc 不支持插入图片，但可以使用 embed_doc_image 实现。
- 修改 docs.rs metadata 确保文档正常编译。
- 推荐尝试文档即代码的实践，简化构建、引用方便、支持版本化。
➡️
