MEP10: Docstring の一貫性#

アブストラクト #

matplotlib には、docstring 間に大きな矛盾があります。これにより、ドキュメントが読みにくくなるだけでなく、貢献者はどの仕様に従うべきかわからないため、より困難になります。一貫して従う明確な docstring 規則が必要です。

API ドキュメントの構成を理解するのは困難です。pyplot や Axes などの一部のページは、巨大で閲覧が困難です。代わりに、詳細なドキュメントにリンクする短い要約表が必要です。さらに、一部の docstring 自体は非常に長く、冗長な情報が含まれています。

ドキュメントの作成には時間がかかり、make.py Makefile ではなくスクリプトを使用します。

詳細な説明 #

matplotlib が Sphinx の使用を開始して以来、作業を容易にする新しいツールと規則が多数利用可能になりました。以下は、提案された docstring の変更のリストです。そのほとんどは、これらの新機能に関係しています。

numpy docstring 形式 #

Numpy docstring 形式: この形式は、docstring を明確なセクションに分割します。各セクションには、生のテキストと HTML の両方で docstring を読みやすくするさまざまな解析規則があります。代替案を検討したり、独自のものを発明したりすることもできますが、Numpy/Scipy コミュニティでよく使用され、理解されているため、これは強力な選択です。

matplotlib のドキュメント文字列のほとんどは、他の項目にリンクするときに明示的な「役割」を使用します。たとえば、:func:`myfunction`. Sphinx 0.4 では、「obj」に設定できる「default_role」があり、あらゆるタイプの Python オブジェクトにポリモーフィックにリンクします。`myfunction`これにより、代わりに書き込むことができます。これにより、docstring を生のテキストとして読みやすく、編集しやすくなります。さらに、Sphinx では現在のモジュールを設定できるため、のようなリンクはのよう`~matplotlib.axes.Axes.set_xlim` に記述できます`~axes.Axes.set_xlim`。

署名のオーバーライド #

matplotlib の多くのメソッドは*argsand**kwargs構文を使用して、関数によって受け入れられるキーワード引数を動的に処理したり、別の関数に委譲したりします。ただし、これは多くの場合、ドキュメントの署名としては役に立ちません。このため、多くの matplotlib メソッドには次のようなものが含まれています。

def annotate(self, *args, **kwargs):
    """
    Create an annotation: a piece of text referring to a data
    point.

    Call signature::

      annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)
    """

これは Sphinx では解析できず、生のテキストではかなり冗長です。Sphinx 1.1 の時点で、autodoc_docstring_signatureconfig 値が True に設定されている場合、Sphinx は docstring の最初の行から置換署名を抽出し、これを可能にします:

def annotate(self, *args, **kwargs):
    """
    annotate(s, xy, xytext=None, xycoords='data',
               textcoords='data', arrowprops=None, **kwargs)

    Create an annotation: a piece of text referring to a data
    point.
    """

明示的な署名は、生成されたドキュメント内の実際の Python 署名を置き換えます。

matplotlib では、numpydoc 拡張機能を有効にする必要があります。これらを matplotlib ソースツリーに含めるか、依存関係として使用するかについて、重要な問題があります。Numpydoc 拡張機能を取得するには、Numpy をインストールするだけでは十分ではありません。これは別のインストール手順です。いずれにせよ、私たちのニーズに合わせてカスタマイズする必要がある限り、それらの変更をアップストリームに提出し、フォークしないように努めるべきです。
すべての docstring を手動で確認し、それらを新しい形式と規則に更新します。相互参照の更新 (から `:func:`myfunc`へ`func`) は、半自動化できる場合があります。これは非常に忙しい作業であり、おそらくこの作業はモジュールごとに分割して、1 人の開発者に過度の負担がかからないようにする必要があります。
autosummary とを使用して API ドキュメントを再編成しますsphinx-autogen。これにより、物語のドキュメンテーションへの影響が最小限になることが期待されます。
サンプルページジェネレーター ( gen_rst.py) を変更して、サンプルからモジュール docstring を抽出し、それをサンプルページの非リテラル部分に含めます。
sphinx-quickstart新しいスタイルの Sphinx Makefile を生成するために使用します。現在の次の機能は、make.py別の方法で対処する必要があります。
- 一部の静的コンテンツのコピー
- 「小さい」ビルドの指定 (例として低解像度の PNG ファイルのみ)

ステップ 1、2、および 3 は相互に依存しています。4 と 5 は独立して実行できますが、5 は 3 に依存しています。

下位互換性 #

これは主に docstring に関係するため、下位互換性への影響は最小限に抑える必要があります。

代替案 #

まだ議論されていません。

MEP10: Docstring の一貫性#

ステータス 番号

ブランチとプルリクエスト #

アブストラクト #

詳細な説明 #

numpy docstring 形式 #

相互参照 #

署名のオーバーライド #

複製ではなくリンク #

オートサマリー拡張 #

関連ドキュメントへのリンクの例 #

help() とブラウザを使用したドキュメント #

実装 #

下位互換性 #

代替案 #