`sphinx.ext.autosummary` – 自動ドキュメントサマリー生成¶

バージョン 0.6 で追加。

この拡張機能は、Epydoc やその他の API ドキュメント生成ツールによって出力されるものと同様の、関数/メソッド/属性のサマリーリストを生成します。これは、docstring が長く詳細な場合に特に役立ち、それぞれを別々のページに配置することで読みやすくなります。

sphinx.ext.autosummary 拡張機能は、2 つの部分でこれを行います。

ドキュメント化された項目へのリンクと、それらの docstring から抽出された短いサマリーブラブ (最初の文) を含むサマリーリストを生成するための autosummary ディレクティブがあります。
autosummary ディレクティブは、そのコンテンツにリストされている項目の短い「スタブ」ファイルも生成します。これらのファイルには、デフォルトでは対応する sphinx.ext.autodoc ディレクティブのみが含まれていますが、テンプレートを使用してカスタマイズできます。

sphinx-autogen スクリプトもコマンドラインから「スタブ」ファイルを生成できます。

.. autosummary::¶

ドキュメント化された項目へのリンクと、それらのそれぞれに対する短いサマリーブラブ (docstring の最初の文) を含む表を挿入します。

autosummary ディレクティブは、オプションで、含まれる項目の toctree エントリとしても機能できます。オプションで、autosummary_generate が True の場合、これらの項目のスタブ .rst ファイルも自動的に生成できます。

たとえば、

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

は次のような表を生成します。

`environment.BuildEnvironment`(app)	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 はデフォルトで、その出力をこのディレクトリに配置します。引数が指定されていない場合、出力はディレクティブを含むファイルと同じディレクトリに配置されます。

caption オプションを使用して、toctree にキャプションを付けることもできます。

バージョン 3.1 で追加: caption オプションが追加されました。
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 で追加。
recursive オプションを指定して、モジュールとサブパッケージのドキュメントを再帰的に生成できます。デフォルトでは無効になっています。たとえば、
```
.. autosummary::
   :recursive:

   sphinx.environment.BuildEnvironment
```
バージョン 3.1 で追加。

sphinx-autogen – 自動ドキュメントスタブページ生成¶

sphinx-autogen スクリプトは、autosummary リストに含まれる項目のスタブドキュメントページを簡単に生成するために使用できます。

たとえば、コマンド

$ sphinx-autogen -o generated *.rst

は、:toctree: オプションが設定されている *.rst ファイル内のすべての autosummary テーブルを読み取り、ドキュメント化されたすべての項目について generated ディレクトリにスタブページを出力します。生成されたページには、デフォルトで次のようなテキストが含まれています。

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

.. autofunction:: sphinx.util.relative_uri

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

詳細については、sphinx-autogen ドキュメントを参照してください。

スタブページの自動生成¶

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

autosummary_context¶: autosummary スタブファイルのテンプレートエンジンのコンテキストに渡す値の辞書。

バージョン 3.1 で追加。

autosummary_generate¶

見つかったすべてのドキュメントを autosummary ディレクティブについてスキャンし、それぞれについてスタブページを生成するかどうかを示すブール値。デフォルトで有効になっています。

スタブページを生成するドキュメントのリストにすることもできます。

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

バージョン 2.3 で変更: autodoc-skip-member イベントを autodoc と同様に発行します。

バージョン 4.0 で変更: デフォルトで有効になりました。

autosummary_generate_overwrite¶: 真の場合、autosummary は生成されたスタブページによって既存のファイルを上書きします。デフォルトは true（有効）です。

バージョン 3.0 で追加されました。

autosummary_mock_imports¶: この値には、モックアップするモジュールのリストが含まれています。autodoc_mock_importsの詳細については、そちらを参照してください。デフォルトはautodoc_mock_importsです。

バージョン 2.0 で追加されました。

autosummary_imported_members¶: モジュールでインポートされたクラスと関数を記述するかどうかを示すブール値フラグです。デフォルトはFalseです。

バージョン 2.1 で追加されました。

バージョン 4.4 で変更されました: autosummary_ignore_module_allがFalseの場合、この設定値は__all__にリストされているメンバーについては無視されます。

autosummary_ignore_module_all¶

Falseの場合、モジュールに__all__属性が設定されていると、autosummary は__all__にリストされているすべてのメンバーを記述し、それ以外のメンバーは記述しません。デフォルトはTrueです。

インポートされたメンバーが__all__にリストされている場合、autosummary_imported_membersの値に関係なく、記述されます。from module import *の動作に合わせるには、autosummary_ignore_module_allをFalseに、autosummary_imported_membersをTrueに設定します。

バージョン 4.4 で追加されました。

autosummary_filename_map¶: オブジェクト名とファイル名をマッピングする辞書です。これは、大文字と小文字を区別しないファイルシステムで、複数のオブジェクトが名前が区別できない場合に、ファイル名の競合を回避するために必要です。

バージョン 3.2 で追加されました。

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

バージョン 1.0 で追加。

HTML Jinja テンプレートと同様に、スタブページテンプレートをカスタマイズできます。テンプレートを参照してください。（TemplateBridgeはサポートされていません。）

注記

スタブテンプレートの調整に多くの時間を費やしている場合は、代わりにカスタムの記述ドキュメントを作成する方が良い場合があります。

Autosummary は次の Jinja テンプレートファイルを使用します。

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

テンプレートでは次の変数が使用できます。

name¶: モジュールとクラスの部分を除く、記述されたオブジェクトの名前です。

objname¶: モジュール部分を除く、記述されたオブジェクトの名前です。

fullname¶: モジュールとクラスの部分を含む、記述されたオブジェクトの完全な名前です。

objtype¶: 記述されたオブジェクトの型。 "module"、"function"、"class"、"method"、"attribute"、"data"、"object"、"exception"、"newvarattribute"、"newtypedata"、"property"のいずれかです。

module¶: 記述されたオブジェクトが属するモジュールの名前です。

class¶: 記述されたオブジェクトが属するクラスの名前です。メソッドと属性の場合のみ使用できます。

underline¶: len(full_name) * '='を含む文字列です。underlineフィルターを使用してください。

members¶: モジュールまたはクラスのすべてのメンバーの名前を含むリストです。モジュールとクラスの場合のみ使用できます。

inherited_members¶: クラスのすべての継承されたメンバーの名前を含むリストです。クラスの場合のみ使用できます。

バージョン 1.8.0 で追加されました。

functions¶: モジュール内の「公開」関数の名前を含むリストです。「公開」とは、名前がアンダースコアで始まらないことを意味します。モジュールの場合のみ使用できます。

classes¶: モジュール内の「公開」クラスの名前を含むリストです。モジュールの場合のみ使用できます。

exceptions¶: モジュール内の「公開」例外の名前を含むリストです。モジュールの場合のみ使用できます。

methods¶: クラス内の「公開」メソッドの名前を含むリストです。クラスの場合のみ使用できます。

attributes¶: クラス/モジュール内の「公開」属性の名前を含むリストです。クラスとモジュールの両方で使用できます。

バージョン 3.1 で変更されました: モジュールの属性がサポートされました。

modules¶: パッケージ内の「公開」モジュールの名前を含むリストです。パッケージであるモジュールとrecursiveオプションがオンの場合のみ使用できます。

バージョン 3.1 で追加。

さらに、次のフィルターを使用できます。

escape(s)¶: RST コンテキストのフォーマットに使用されるテキスト内の特殊文字をエスケープします。たとえば、アスタリスクによって太字にならないようにします。これは、HTML エスケープを行う組み込み Jinja escape フィルターを置き換えます。

underline(s, line='='): テキストにタイトルのアンダーラインを追加します。

たとえば、{{ fullname | escape | underline }}を使用して、ページのタイトルを作成する必要があります。

注記

スタブページではautosummaryディレクティブを使用できます。スタブページはこれらのディレクティブに基づいて生成されます。

sphinx.ext.autosummary – 自動ドキュメントサマリー生成¶

sphinx-autogen – 自動ドキュメントスタブページ生成¶

スタブページの自動生成¶

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

`sphinx.ext.autosummary` – 自動ドキュメントサマリー生成¶