99

私は、C または PHP コードのドキュメントを作成するために Doxygen が好きです。/* .. */私は近日中に Python プロジェクトを予定していますが、Python にはコメントがなく、独自の自己文書化機能も備えていることを覚えていると思います。

私は Doxygen に精通しているので、それを使用して Python ドキュメントを作成するにはどうすればよいですか? 特に注意しなければならないことはありますか？

4

5 に答える 5

90

doxypy入力フィルターを使用すると、Doxygen のフォーマット タグのほとんどすべてを標準の Python docstring フォーマットで使用できます。C++ と Python が混在する大規模なゲーム アプリケーション フレームワークのドキュメント化に使用していますが、うまく機能しています。

于 2009-01-30T21:30:02.833 に答える
68

これは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ドキュメントの慣行を順守し、それが特別なdoxygenコマンドに干渉することを期待しているのではないでしょうか。

于 2008-09-12T11:11:03.123 に答える
21

私が理解しているように、Sphinx は主に、ソース コードから独立して記述されたドキュメントをフォーマットするためのツールです。

Python docstring から API ドキュメントを生成するための主要なツールはpdocとpydoctorです。TwistedおよびBazaar用に pydoctor が生成した API ドキュメントを次に示します。

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

于 2008-09-12T21:04:48.063 に答える
14

もう 1 つの非常に優れたドキュメント ツールはsphinxです。これは、今後の python 2.6ドキュメントで使用され、djangoや他の多くの python プロジェクトで使用されます。

スフィンクスのウェブサイトから：

  • 出力形式: HTML (Windows HTML Help を含む) および LaTeX (印刷可能な PDF バージョン用)
  • 広範な相互参照: セマンティック マークアップと、関数、クラス、用語集の用語、および同様の情報への自動リンク
  • 階層構造: ドキュメント ツリーを簡単に定義し、兄弟、親、および子への自動リンクを使用
  • 自動インデックス: 一般インデックスとモジュール インデックス
  • コード処理: Pygments ハイライターを使用した自動ハイライト
  • 拡張機能: コード スニペットの自動テスト、Python モジュールからのドキュメント文字列の組み込みなど
于 2008-09-12T13:48:59.313 に答える