开始为 django 应用程序编写文档 [关闭]

Question

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

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

Answer 1

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

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