2023-06: OpenDAL 的文档即代码实践

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 确保文档正常编译。

推荐尝试文档即代码的实践，简化构建、引用方便、支持版本化。