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

バージョン 0.6 で追加.

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

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

  1. ドキュメントが書かれた要素へのリンクと、docstringから抽出した短い概要の文を含んだサマリーのリストを生成する、 autosummary ディレクティブがあります。

  2. オプションで、 sphinx-autogen か、新しい autosummary_generate 設定値を autosummary ディレクティブに列挙されているエントリーに対する短い”スタブ”ファイルを生成するために使うこともできます。デフォルトでは、これらのファイルは sphinx.ext.autodoc ディレクティブにのみ含まれていますが、テンプレートでカスタマイズできます。

.. autosummary::

それぞれのアイテムごとに、ドキュメントされたアイテムとblurb(docstringの最初の文)を含むテーブルを挿入します。

autosummary ディレクティブはおまけとして、含まれている項目への toctree のような働きもします。その場合、それらのアイテムに対するスタブの .rst ファイルが自動的に生成されます。

サンプル:

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

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

environment.BuildEnvironment(srcdir, ...)

ReSTファイルが翻訳される環境。

util.relative_uri(base, to)

base から to に対する相対URL。

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

オプション

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

    .. autosummary::
       :toctree: DIRNAME
    
       sphinx.environment.BuildEnvironment
       sphinx.util.relative_uri
    

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

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

    .. autosummary::
       :nosignatures:
    
       sphinx.environment.BuildEnvironment
       sphinx.util.relative_uri
    
  • template オプションを使用することで、カスタムのテンプレートを指定できます

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

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

    バージョン 1.0 で追加.

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: オプションで設定されたディレクトリにファイルを出力します。

スタブページの自動作成

もしも、 sphinx-autogen を使用してスタブページを作成したくない場合は、以下の設定値も使用できます:

autosummary_generate

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

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

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

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

バージョン 1.0 で追加.

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

注釈

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

Autosummary uses the following Jinja template files:

  • autosummary/base.rst – 代替のテンプレート

  • autosummary/module.rst – モジュールのためのテンプレート

  • autosummary/class.rst – クラスのためのテンプレート

  • autosummary/function.rst – 関数のためのテンプレート

  • autosummary/attribute.rst – クラス属性のためのテンプレート

  • autosummary/method.rst – クラスメソッドのためのテンプレート

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

name

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

objname

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

fullname

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

module

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

class

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

underline

A string containing len(full_name) * '='. Use the underline filter instead.

members

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

functions

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

classes

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

exceptions

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

methods

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

attributes

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

Additionally, the following filters are available

escape(s)

Escape any special characters in the text to be used in formatting RST contexts. For instance, this prevents asterisks making things bolt. This replaces the builtin Jinja escape filter that does html-escaping.

underline(s, line='=')

Add a title underline to a piece of text.

For instance, {{ fullname | escape | underline }} should be used to produce the title of a page.

注釈

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