python - django アプリケーションのドキュメントを書き始める

Question

私の Django ベースのプロジェクトのドキュメントを書きたいと思います。Django の人々は、この目的のために reStructureText と Sphinx を使用していることがわかりました。以下の質問があります。

• reStructureText と Sphinx を使用してドキュメントを書き始めるにはどうすればよいですか?
• ドキュメントを適切に整理し、理解しやすく、管理しやすいようにバージョン管理するには、どのようなベスト プラクティスに従う必要がありますか?

Answer 1

sphinxのドキュメントはここにあります：https ：//www.sphinx-doc.org

• を実行することから始めますsphinx-quickstart。
• 「よく整理された」は本当にあなた自身の問題です。これはあなたの好みとあなたのプロジェクトに依存します。
• 「管理が簡単」：コードドキュメントにdoctestを含め、スフィンクスのセットアップにautodocを含めます。このようにして、テストスーツを実行するときに、ドキュメントがコードと一致するかどうかを常に確認できます。（ただし、ドキュメントのテストにはdoctestのみを使用してください。コードをテストするには、個別の単体テストを行う必要があります。そうしないと、ドキュメントが使用できなくなります...）
• 「わかりやすい」というのは、本当にあなた次第です。