ドキュメンテーション¶

可読性は、プロジェクトとコードのドキュメント両方ともPython開発者の主な焦点となっています。いくつかの簡単なベストプラクティスに従えば、あなたと他の人の両方に多くの時間を節約できます。

プロジェクトのドキュメント¶

ルートディレクトリにある README ファイルは、プロジェクトのユーザと管理者の両方に一般的な情報を与えるべきです。生のテキストでなければなりません。例えば reStructuredText やMarkdownのような読みやすいマークアップで記述します。プロジェクトやライブラリの目的（ユーザーがプロジェクトについて知っていることを前提としない）、ソフトウェアの主なソースのURL、および基本的なクレジット情報を説明する行がいくつか含まれていなければなりません。このファイルは、コードの読者のための主要なエントリポイントです。

Pythonでは INSTALL ファイルはあまり必要ありません。インストール指示は pip install module や python setup.py install のように1つのコマンドに短縮され、README ファイルに追加されます。

LICENSE ファイルは常に存在し、ライセンスを指定する必要がありますその下でソフトウェアは一般に公開されます。

TODO ファイルまたは TODO セクション README は、コードの開発予定を列挙します。

CHANGELOG ファイルまたはセクション README は、最新バージョンのコードベースの変更の概要をコンパイルする必要があります。

プロジェクト出版¶

プロジェクトによっては、ドキュメントに次のコンポーネントの一部またはすべてが含まれている場合があります。

introduction には、1つまたは2つの非常に単純化されたユースケースを使用して、製品でできることの概要を非常に簡単に示してください。これはあなたのプロジェクトのための30秒のピッチです。

チュートリアル では、いくつかの主要なユースケースをより詳細に示す必要があります。読者は、実際のプロトタイプをセットアップするための段階的な手順に従います。

APIリファレンス は通常、コードから生成されます（参照 docstrings）。これは、公開されているすべてのインターフェース、パラメーター、および戻り値をリストします。

開発者ドキュメント は、潜在的な貢献者を対象としています。これには、プロジェクトのコード規約と一般的なデザイン戦略が含まれます。

Sphinx¶

Sphinx は、最も人気のあるPythonドキュメントツールです。 これを使用します。 reStructuredText マークアップ言語を、HTML、LaTeX（印刷可能なPDF版用）、マニュアルページ、プレーンテキストなどの出力フォーマットの範囲に変換します。

あなたの Sphinx docsのための 無料で、素晴らしい ホスティングもあります: Read The Docs。これを使用します。ドキュメントの再構築が自動的に行われるように、ソースリポジトリへのコミットフックを設定することができます。

実行すると、Sphinx はコードをインポートし、Pythonのイントロスペクション機能を使用して、すべての関数、メソッド、クラスのシグネチャを抽出します。また付属のドキュメントストリングを抽出し、それをすべて構造化された、簡単に読めるドキュメントにコンパイルしてプロジェクトに合わせます。

注釈

SphinxはAPIの生成で有名ですが、一般的なプロジェクトのドキュメントでもうまく機能します。このガイドはSphinx_ で構築され、 Read The Docs でホスティングされています。

reStructuredText¶

ほとんどのPythonのドキュメントはreStructuredText_で書かれています。 Markdownのように、すべてのオプションの拡張が組み込まれています。

reStructuredText Primer と reStructuredText Quick Reference は、その構文に慣れるのに役立ちます。

コードドキュメントのアドバイス¶

コメントはコードを明確にし、コードを分かりやすくする目的で追加されています。 Pythonでは、コメントはハッシュ (数字記号) (#) で始まります。

Pythonでは、docstrings はモジュール、クラス、関数を記述します:

def square_and_rooter(x):
    """Return the square root of self times self."""
    ...

一般的に、 PEP 8#comments (“Python Style Guide”) のコメントセクションに従ってください。 docstringの詳細については、PEP 0257#specification （Docstring規約ガイド）を参照してください。

コードのセクションのコメント¶

トリプルクォート文字列を使用してコードにコメントを付けないでください。 grepのような行指向のコマンドラインツールは、コメント付きコードが非アクティブであることを認識しないため、これは良い方法ではありません。コメント行ごとに適切なインデントレベルでハッシュを追加する方がよいでしょう。あなたのエディタはおそらくこれを簡単に実行する能力があり、コメント/コメント解除トグルを学ぶ価値があります。

ドキュメンテーションとマジック¶

一部のツールでは、ドキュメントテストロジックなどのドキュメントよりも多くの動作を埋め込むためにドキュメントストリングを使用します。それらは素晴らしいことができますが、あなたは vanilla に間違って行くことはありません “ここでこれが何かをしています”。

Sphinx のようなツールは、ドキュメントストリングをreStructuredTextとして解析し、HTMLとして正しくレンダリングします。これにより、サンプルコードのスニペットをプロジェクトのドキュメントに埋め込むことが非常に簡単になります。

さらに、Doctest_は、Pythonのコマンドライン（ “>>>”という接頭辞）の入力と同じように見える埋め込みdocstringをすべて読み込み、コマンドの出力が次の行のテキストと一致するかどうかを確認します。これにより、開発者は実際のサンプルと関数の使用方法をソースコードとともに埋め込むことができ、副作用として、コードがテストされ、動作することが保証されます。

def my_function(a, b):
    """
    >>> my_function(2, 3)
    6
    >>> my_function('a', 3)
    'aaa'
    """
    return a * b

Docstringsとブロックコメント¶

これらは交換できません。関数またはクラスの場合、先頭のコメントブロックはプログラマーのメモです。 docstringは、関数またはクラスの operation を記述します:

# This function slows down program execution for some reason.
def square_and_rooter(x):
    """Returns the square root of self times self."""
    ...

ブロックコメントとは異なり、docstrings はPython言語自体に組み込まれています。つまり、Pythonの強力なイントロスペクション機能をすべて使用して、最適化されたコメントと比較して、実行時に docstrings にアクセスすることができます。 Docstringは、ほとんどすべてのPythonオブジェクトのための __doc__ dunder属性と組み込みの help() 関数の両方からアクセスできます。

ブロックのコメントは通常、コードの何が何をしているのか、アルゴリズムの詳細を説明するために使われますが、docstringは他のユーザにあなたのコードを説明するためのものです（6ヶ月以内に） how 関数、クラス、モジュールの汎用目的に使用できます。

ドキュメントストリングを書く¶

関数、メソッド、またはクラスの複雑さに応じて、1行のdocstringが完全に適切かもしれません。これらは一般的に次のような本当の明白な場合に使用されます:

def add(a, b):
    """Add two numbers and return the result."""
    return a + b

docstringは、理解しやすい方法で関数を記述する必要があります。簡単な関数やクラスのような簡単な場合は、関数のシグネチャ (つまり、add(a, b) -> result) をdocstringに埋め込むだけで済みます。これは、Pythonの inspect モジュールでは、必要に応じてこの情報を見つけるのがとても簡単で、ソースコードを読むことで簡単に入手できるからです。

しかし、より大規模なプロジェクトやより複雑なプロジェクトでは、関数、それが行うこと、発生する可能性のある例外、返されるもの、またはパラメータに関する関連する詳細に関する情報を多く与えることは、しばしば良い考えです。

コードのより詳細なドキュメンテーションについては、Numpyプロジェクトがよく使われます。 Numpy style と呼ばれることもあります。これは前の例をいくつか追加していますが、開発者はメソッド、関数、またはクラスに関するさらに多くの情報を含めることができます。:

def random_number_generator(arg1, arg2):
    """
    Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    int
        Description of return value

    """
    return 42

sphinx.ext.napoleon プラグインは、Sphinx がこのスタイルのドキュメントストリングを解析できるようにし、NumPyスタイルのドキュメントストリングをプロジェクトに簡単に組み込むことができます。

その日の終わりには、ドキュメントストリングを書くためにどのようなスタイルが使われているかは重要ではありません。その目的は、コードを読んだり変更したりする必要がある人のためのドキュメンテーションとして役立つことです。それを正しく理解できるものであれば、関連するポイントを得ることができます。

ドキュメントストリングをさらに読むには、相談してください PEP 257

その他のツール¶

あなたは出回っているこれらを見るかもしれません。 Sphinx を使います。

Pycco: Pyccoは “識字プログラミングスタイルのドキュメント生成プログラム” であり、node.js Docco の一部です。それはコードをサイド・バイ・サイドのHTMLコードとドキュメントにします。

Ronn: RonnはUnixのマニュアルを作成しています。これは、人間が読めるテキストファイルをターミナル表示のためにroffに、そしてウェブのHTMLに変換します。

Epydoc: Epydocは廃止されました。代わりに Sphinx を使用してください。

MkDocs: MkDocsは、Markdownでプロジェクトのドキュメンテーションを構築するための、高速でシンプルな静的サイト生成ツールです。