.. highlight:: rest

sphinx.ext.autosummary – autodocのサマリーの生成

バージョン 0.6 で追加.

この拡張機能は、Epydocや他のAPIドキュメント生成ツールような、関数、メソッド、属性のサマリーのリストを生成します。この機能は、作成中のシステムのdocstringが長く、詳細まで記述されていて、読みやすくするためにページを分けて出力されている場合に便利です。

sphinx.ext.autosummary は以下の２つの機能を持っています:

1. ドキュメントが書かれた要素へのリンクと、docstringから抽出した短い概要の文を含んだサマリーのリストを生成する、 autosummary ディレクティブがあります。
2. 便利なスクリプト sphinx-autogen あるいは、新しい設定値の autosummary_generate を使用して、短い”スタブ”ファイルを生成することができます。このファイルは autosummary ディレクティブ内に書かれているエントリーが記述されます。デフォルトでは、関連する sphinx.ext.autodoc ディレクティブだけが含まれます。

.. autosummary::

ドキュメントされている項目へのリンクを含むテーブルを挿入します。この中には、それぞれに対するサマリー文(docstringの最初の文)も含まれます。 autosummary ディレクティブはおまけとして、含まれている項目への toctree のような働きもします。

サンプル:

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

これは以下のようなテーブルを作成します:

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

.. currentmodule:: sphinx.ext.autosummary

autosummaryは、 autodoc が行っているのと同様に、 autodoc-process-docstring イベントと、 autodoc-process-signature イベントをフックすることで、 docstringとシグニチャの前処理を行います。

オプション

• autosummary テーブルを toctree のエントリーと同様に提供したい場合には、以下のようにします:

  .. autosummary::
     :toctree: ディレクトリ名
  
     sphinx.environment.BuildEnvironment
     sphinx.util.relative_uri

  toctree オプションは、このディレクティブに含まれるエントリーのリストに対するスタブのページを作成する、 sphinx-autogen スクリプトにも伝えられます。このオプションは、ディレクトリ名を引数として受け取ります。デフォルトでは sphinx-autogen はこのディレクトリに出力します。もしも引数が与えられなかった場合には、そのディレクティブが含まれているファイルがある、同じディレクトリに出力します。

• 関数のシグネチャを、:dir:autosummary が出力するリストの中に入れたくない場合には、 nosignatures オプションを設定します:

  .. autosummary::
     :nosignatures:
  
     sphinx.environment.BuildEnvironment
     sphinx.util.relative_uri

• template オプションを使用することで、カスタムのテンプレートを指定することができます

  サンプル:

  .. autosummary::
     :template: mytemplate.rst
  
     sphinx.environment.BuildEnvironment

  このサンプルのコードをビルドすると、 templates_path に含まれる、 mytemplate.rst という名前のテンプレートファイルを使用して、エントリーのすべてのリストのページを生成します。詳しくは テンプレートのカスタマイズ を参照してください。

sphinx-autogen – autodocのスタブページを生成

sphinx-autogen スクリプトは autosummary にリストアップされた要素のためのドキュメントページのスタブを簡単に生成するのに使用されます。

以下のようにコマンドを起動したとします:

$ sphinx-autogen -o generated *.rst

このコマンドを実行すると、 *.rst にマッチして、なおかつ :toctree: オプションを持つすべてのファイルを読み込み、その中に定義されているすべての autosummary テーブルを読み込みます。読み込んだ後はすべてのドキュメント付けされた要素に関連するスタブページを generated ディレクトリに出力します。デフォルトでは、以下のようなテキストを含むページが生成されます:

sphinx.util.relative_uri
========================

.. autofunction:: sphinx.util.relative_uri

もしも -o オプションが指定されなかった場合には、 :toctree: オプションで設定されたディレクトリにファイルを出力します。

スタブページの自動作成

autosummary_generate

ブーリアン値で、autosummaryディレクティブのために書かれたドキュメントをすべてスキャン して、それぞれのスタブページを作成するかどうか決定します。

スタブページを作成すべきドキュメントをリスト表示するのにも使用することができます。

ディレクティブの :toctree: オプションで指定されたディレクトリに新しいファイルを配置します。

テンプレートのカスタマイズ

テンプレート のセクションで説明しているのと同じ、Sphinxの標準的なHTMLのJinjaテンプレートを使って、スタブページのテンプレートをカスタマイズすることができます。ただし、 TemplateBridge はサポートしていません。

ノート

もしも、スタブのテンプレートをカスタマイズするのに長い時間をかけているということが分かった場合には、autosummaryによる自動生成をやめて、自分でスタブを書いていく方がいいかもしれません。

autosummaryは以下のテンプレートファイルを使用します:

• autosummary/base.rst – 代替のテンプレート
• autosummary/module.rst – モジュールのためのテンプレート
• autosummary/class.rst – クラスのためのテンプレート
• autosummary/function.rst – 関数のためのテンプレート
• autosummary/attribute.rst – クラス属性のためのテンプレート
• autosummary/method.rst – クラスメソッドのためのテンプレート

テンプレートの中では以下の変数名が利用可能です:

sphinx.ext.autosummary.name

ドキュメントの対象となっているオブジェクトの名前です。モジュールなやクラス名の部分は含まれません。

sphinx.ext.autosummary.objname

ドキュメント対象となっているオブジェクトの名前です。モジュール名の部分は含まれません。

sphinx.ext.autosummary.fullname

ドキュメント対象となっているオブジェクトの名前です。モジュール名、クラス名も含みます。

sphinx.ext.autosummary.module

ドキュメント対象のオブジェクトが属しているモジュールの名前です。

sphinx.ext.autosummary.class

ドキュメント対象のオブジェクトが属すクラスの名前です。メソッドと属性が対象の場合だけ利用できます。

sphinx.ext.autosummary.underline

len(full_name) * '=' の実行結果です。

sphinx.ext.autosummary.members

モジュールやクラスに属す、すべてのメンバーの名前のリストです。モジュールとクラスが対象の場合のみ利用できます。

sphinx.ext.autosummary.functions

モジュールの”公開”関数の名前を含むリストです。ここでの”公開”は、名前の最初の文字がアンダースコア以外のものを意味しています。対象がモジュールの場合のみ利用できます。

sphinx.ext.autosummary.classes

モジュールの”公開”クラスの名前を含むリストです。対象がモジュールの場合のみ利用できます。

sphinx.ext.autosummary.exceptions

モジュールの”公開”例外クラスの名前を含むリストです。対象がモジュールの場合のみ利用できます。

sphinx.ext.autosummary.methods

クラスの”公開”メソッドの名前を含むリストです。対象がクラスの場合のみ利用できます。

sphinx.ext.autosummary.methods(ここ間違いです。問い合わせ中)

クラスの”公開”属性の名前を含むリストです。対象がクラスの場合のみ利用できます。

ノート

autosummay ディレクティブは、スタブページの中でも使用することができます。スタブページは、これらのディレクティブを元に生成されます。