doxygen を使用して Python コードを文書化する方法 [終了]

StackOverflow https://stackoverflow.com/questions/58622

質問

C または PHP コードのドキュメントを作成するのに doxygen が好きです。私は今後 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 が ## ブロックまたは """ ブロック内のコメントを検出できれば、ほとんどの作業が完了し、特殊なコマンドを使用できるようになるようです。どちらの場合も。おそらく彼らは、「"」を使用する人々がより Python 的なドキュメントの実践に従うことを期待しており、それが特殊な doxygen コマンドを妨げることになるのでしょうか?

他のヒント

の ドクシー input フィルターを使用すると、Doxygen のほぼすべての書式設定タグを標準の Python docstring 形式で使用できます。私はこれを C++ と Python が混在した大規模なゲーム アプリケーション フレームワークの文書化に使用していますが、うまく機能しています。

私の理解では、Sphinx は主に、ソース コードとは独立して書かれたドキュメントをフォーマットするためのツールです。

Python ドキュメント文字列から API ドキュメントを生成するための主要なツールは次のとおりです。 pdoc そして パイドクター. 。pydoctor が生成した API ドキュメントは次のとおりです。 ツイスト そして バザール.

もちろん、作業中に docstring を確認したいだけの場合は、「」があります。pydoc" コマンド ライン ツールと同様に、 help() 対話型インタープリタで利用できる機能です。

結局、選択肢は 2 つだけです。

Doxygen を使用してコンテンツを生成するか、Sphinx* を使用してコンテンツを生成します。

  1. ドキシゲン:これは、ほとんどの Python プロジェクトで選択されるツールではありません。しかし、C または C++ で書かれた他の関連プロジェクトを扱う必要がある場合には、それが理にかなっている可能性があります。このために、次を使用して Doxygen と Python 間の統合を改善できます。 ドクシーピーピー.

  2. スフィンクス:Python プロジェクトを文書化するための事実上のツール。ここには 3 つのオプションがあります。手動、半自動 (スタブ生成)、および完全自動 (Doxygen のような)。

    1. 手動 API ドキュメントについては、Sphinx を使用してください。 オートドキュメント. 。これは、API によって生成された要素が埋め込まれたユーザー ガイドを作成するのに最適です。
    2. 半自動の場合はSphinxがあります 自動要約. 。sphinx-autogen を呼び出すようにビルド システムをセットアップするか、次のコマンドを使用して Sphinx をセットアップすることができます。 autosummary_generate 構成。自動要約を含むページを設定してから、ページを手動で編集する必要があります。オプションはありますが、このアプローチでの私の経験では、非常に多くの構成が必要になり、最終的には新しいテンプレートを作成した後でさえ、バグが見つかり、何がパブリック API として公開され、何が公開されていないのかを正確に判断することが不可能でした。私の意見では、このツールは手動編集が必要なスタブ生成に適しており、それ以上のものはありません。マニュアルで終わるショートカットのようなものです。
    3. 全自動。これは何度も批判されてきましたが、長い間、Sphinx と統合された優れた完全自動 Python API ジェネレーターはありませんでした。 AutoAPI 来ました、ブロックの新しい子です。これは、Python での自動 API 生成には断然最適です (注:恥知らずな自己宣伝）。

他にも注意すべきオプションがあります。

  • 息をする:これは非常に良いアイデアとして始まりましたが、Doxygen を使用する他の言語のいくつかの関連プロジェクトで作業する場合には理にかなっています。このアイデアは、Doxygen XML 出力を使用し、それを Sphinx にフィードして API を生成することです。したがって、Doxygen のすべての利点を維持し、ドキュメント システムを Sphinx に統合できます。理論的には素晴らしい。さて、実際に私が最後にチェックしたとき、プロジェクトは実稼働の準備ができていませんでした。
  • パイドクター*:非常に特殊です。独自の出力を生成します。Sphinx との基本的な統合と、優れた機能がいくつかあります。

もう 1 つの非常に優れたドキュメント ツールは次のとおりです。 スフィンクス. 。今後の Python 2.6 で使用されます。 ドキュメンテーション そして、によって使用されます ジャンゴ 他にもたくさんの Python プロジェクトがあります。

スフィンクスのウェブサイトより：

  • 出力フォーマット:HTML (Windows HTML ヘルプを含む) および LaTeX (印刷可能な PDF バージョン用)
  • 広範な相互参照:関数、クラス、用語集、および同様の情報に対するセマンティック マークアップと自動リンク
  • 階層構造:兄弟、親、子への自動リンクを備えたドキュメント ツリーの簡単な定義
  • 自動インデックス:一般インデックスとモジュールインデックス
  • コード処理:Pygments ハイライターを使用した自動ハイライト
  • 拡張機能:コード スニペットの自動テスト、Python モジュールからの docstring の組み込みなど
ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top