在“文档佳肴”专栏中，我们经常关注编写文档，但这并非故事的全部。如果作者写了整篇文档却没有读者，那又有什么用呢？文档一旦写好，就必须展示在用户面前才能被阅读。对于超出简单自述文件的任何内容，这都可能是一个挑战；通常文档编写者需要设计、托管基础设施、搜索工具等等。一个项目旨在让这一切变得更容易。
Read the Docs 是一个开源（MIT 许可）项目，始于 2010 年的 Django Dash 活动。该项目的目标是通过减少障碍来提高文档的数量和质量。虽然 Read the Docs 无法为您编写文档，但它确实可以处理从您的源代码管理系统自动构建文档。文档以 HTML 和 PDF 格式呈现，并包含全文搜索。
成千上万的开源项目将其文档托管在 Read the Docs 网站上，其他项目则使用 Read the Docs 代码进行自托管。此外，该团队还为商业和私人用途启动了付费服务。
Read the Docs 解决了这么多问题，你为什么不使用它呢？ 主要原因可能是如果您的文档不是用 reStructured Text 编写的。Read the Docs 使用 Sphinx 进行渲染，因此在 Sphinx 支持其他标记语言之前，您的选择是有限的。但并非没有希望：Read the Docs 团队为 Sphinx 添加了 CommonMark 支持，因此如果您愿意，可以添加您需要的任何语言。
当然，还有其他方式可以为 Read the Docs 做出贡献。最迫切的需求是支持和运营团队需要更多人手。支持团队成员通过 GitHub 问题帮助用户诊断和解决问题。运营团队轮流值班，以保持网站 24/7 全天候运行。有关这些贡献的更多信息，请访问团队页面。也可以通过定期黄金订阅或向可持续发展活动一次性捐款来提供经济支持。
有了 Read the Docs，发布您的文档到用户可以找到的地方，就再也没有借口了。
您有 Read the Docs 使用经验想要分享吗？请在评论中告知我们，或提交一篇“文档佳肴”文章提案。
1 条评论