python - 开始为 django 应用程序编写文档

Question

我想为我的一个基于 Django 的项目编写文档。我发现 Django 人为此使用 reStructureText 和 Sphinx。我有以下疑问。

• 如何开始使用 reStructureText 和 Sphinx 编写文档？
• 我应该遵循哪些最佳实践，以使文档保持井井有条、易于理解和易于管理的版本化？

Answer 1

狮身人面像的文档在这里：https ://www.sphinx-doc.org

• 你从运行开始sphinx-quickstart。
• “井井有条”真的是你自己的事。这取决于你的品味和你的项目。
• “易于管理”：在您的代码文档中包含doctests ，在 sphinx 设置中包含autodoc 。这样，当您运行测试套件时，您始终可以查看您的文档是否与您的代码匹配。（但只使用 doctest 来测试你的文档，测试你的代码，你应该有单独的单元测试，否则文档将无法使用......）
• 至于“易于理解”，这真的取决于你。