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

Question

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

• 如何开始使用reStructureText和Sphinx编写文档？
• 我应该遵循哪些最佳做法，以便文档整齐有序，版本易于理解且易于管理？

谢谢和问候

Answer 1

sphinx的文档在这里：http://sphinx.pocoo.org/

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