python - Python クラスのドキュメントの作成

Question

私は、実際のコードを実行するのは私だけで、経験の浅い 2 人のプログラマー (自分が経験豊富だと考えるのは恐ろしいことです!) が、プログラム全体を監視し、提案するプロジェクトを開始しようとしています。

私が書いたコードに基づいて、クラスと関数のドキュメントを提供するために使用できる優れた (無料の) システムはありますか? データの構造を理解するのに大いに役立つでしょう。

Answer 1

私は、epydocを使用して、埋め込まれた docstring から Python モジュールのドキュメントを生成しました。非常に使いやすく、見栄えの良い出力を複数の形式で生成します。

Answer 2

python.org は現在、ドキュメントにsphinxを使用しています。

個人的には、epydoc よりも sphinx の出力の方が好きです。また、再構成されたテキストは、epydoc マークアップよりも docstrings の方が読みやすいと感じています。

Answer 3

Sphinxは、単純な API ドキュメントが提供する以上の非常に詳細で有益なドキュメントを生成するのに役立ちます。ただし、多くの場合、この種のドキュメントには wiki を使用する方が適切です。また、コードの使用方法を言葉で文書化するのではなく、コードの使用法を示す機能テストを作成することも検討してください。

Epydocは、docstring をスキャンしてコードを調べて API ドキュメントを生成するのは得意ですが、より詳細な情報を提供するのは必ずしも得意ではありません。

プロジェクトに両方のタイプのドキュメントを用意することには利点があります。ただし、時間に追われている場合は、ドキュメントよりも優れたテスト カバレッジと意味のあるテストを用意する方が常に有益です。

Answer 4

私が自分のプロジェクトで Sphinx を使用しているのは、見栄えが良いという理由だけでなく、Sphinx がコンピューターだけでなく人間が読むためのドキュメントを作成することを奨励しているからでもあります。

epydoc のようなツールによって作成された JavaDoc スタイルのドキュメントは、読むのがとても悲しいと思います。API ドキュメントにギャップがあるという理由だけで、プログラマーが引数と戻り値の型を無意識に「ドキュメント化」していることがよくあります。したがって、コード行はこれになります（これはJavaのように見えるはずですが、Javaを書いてからしばらく経っているので、コンパイルできない可能性があります...）

/**
 * Set the name.
 *
 * @param firstName the first name.
 * @param lastName the last name.
 */
public void setName(String firstName, String lastName) {
  this.firstName = firstName;
  this.lastName = lastName;
}

このいわゆる「ドキュメント」に含まれる情報はごくわずかです。autodoc私はあなたが（プラグインを使用して）単純に書くSphinxの方法をはるかに好みます

.. autofunction:: set_name

Sphinx はドキュメントに次のような行を追加します。

set_name( first_name, last_name)

そのことから、すべての Python プログラマーは何が起こっているのかを知る必要があります。

Answer 5

can-i-document-python-code-with-doxygen-and-does-it-make-senseへの回答、特にEpydocとpydoctorについて言及している回答を参照してください。