开始为Django应用编写文档

Question

我想为我的一个基于Django的项目写文档。我发现Django的开发者们通常使用reStructureText和Sphinx来完成这个任务。我有以下几个问题。

• 我该如何开始使用reStructureText和Sphinx来写文档呢？
• 我应该遵循哪些最佳实践，以确保文档结构清晰、版本管理方便、易于理解和维护呢？

Answer 1

sphinx的文档在这里：https://www.sphinx-doc.org

• 首先，你需要运行 sphinx-quickstart 命令。
• 关于“组织得很好”，这其实是你自己的事情。具体要怎么组织，完全看你的喜好和项目的需求。
• 至于“易于管理”，你可以在代码文档中加入 doctests，并在sphinx的设置中使用 autodoc。这样，当你运行测试时，就能随时检查文档是否和代码一致。（不过，doctest只用来测试文档，测试代码的话要有单独的单元测试，否则文档可能会变得没用...）
• 至于“易于理解”，这完全取决于你自己。