私はDoxygenがCまたはPHPコードのドキュメントを作成するのが好きです。私は今後のPythonプロジェクトを持っていますが、Pythonには/* .. */コメントがなく、Pythonのように文書化する独自の自己文書化機能もあることを覚えていると思います。
私はDoxygenに精通しているので、それを使用してPythonドキュメントを作成するにはどうすればよいですか？特に気をつけなければならないことはありますか？
回答:
これはdoxygenのWebサイトに記載されていますが、ここに要約します。
doxygenを使用してPythonコードを文書化できます。Pythonドキュメントの文字列構文を使用できます。
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
この場合、コメントはdoxygenによって抽出されますが、特別なdoxygenコマンドを使用することはできません。
または、（doxygenのCスタイル言語と同様に#）メンバーの前の最初の行にあるコメントマーカー（）を2倍にすることができます。
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
その場合、特別なdoxygenコマンドを使用できます。特定のPython出力モードはありませんが、に設定OPTMIZE_OUTPUT_JAVAすることで結果を改善できるようYESです。
正直なところ、私はその違いに少し驚いています-doxygenが##ブロックまたは "" "ブロックのコメントを検出できるようになると、ほとんどの作業が完了し、で特別なコマンドを使用できるようになります。どちらの場合でも、「」を使用している人々がより多くのPythonicドキュメントの慣行に従うことを期待しているのでしょうか。
doxypy入力フィルターを使用すると、Doxygenのほとんどすべてのフォーマットタグを標準のPythondocstringフォーマットで使用できます。大規模なC ++とPythonの混合ゲームアプリケーションフレームワークを文書化するために使用しますが、うまく機能しています。
結局のところ、2つのオプションしかありません。
Doxygenを使用してコンテンツを生成するか、Sphinx *を使用してコンテンツを生成します。
Doxygen：ほとんどのPythonプロジェクトに最適なツールではありません。ただし、CまたはC ++で記述された他の関連プロジェクトを処理する必要がある場合は、それが理にかなっている可能性があります。このために、doxypypyを使用してDoxygenとPythonの間の統合を改善できます。
Sphinx：Pythonプロジェクトを文書化するための事実上のツール。ここには、手動、半自動（スタブ生成）、および完全自動（Doxygenのような）の3つのオプションがあります。
autosummary_generateconfigを使用してSphinxをセットアップすることができます。自動要約を使用してページを設定してから、手動でページを編集する必要があります。オプションはありますが、このアプローチでの私の経験では、構成が多すぎるため、新しいテンプレートを作成した後でも、バグと、パブリックAPIとして公開されているものと公開されていないものを正確に判断できないことがわかりました。私の意見では、このツールは手動編集のみを必要とするスタブ生成に適しています。マニュアルになってしまうショートカットのようなものです。注意すべき他のオプションがあります：
__all__。
他の非常に優れたドキュメントツールはsphinxです。これは、今後のpython 2.6ドキュメントで使用され、djangoで使用されます。や他の多くのpythonプロジェクトでます。
スフィンクスのウェブサイトから：