sphinx.ext.autosummary
-- autodocのサマリーの生成¶
Added in version 0.6.
この拡張機能は、Epydocや他のAPIドキュメント生成ツールのような、関数、メソッド、属性のサマリーのリストを生成します。この機能は、作成中のシステムのdocstringが長く、詳細まで記述されていて、読みやすくするためにページを分けて出力されている場合に便利です。
sphinx.ext.autosummary
は以下の2つの機能を持っています:
ドキュメントが書かれた要素へのリンクと、docstringから抽出した短い概要の文を含んだサマリーのリストを生成する、
autosummary
ディレクティブがあります。A
autosummary
directive also generates short "stub" files for the entries listed in its content. These files by default contain only the correspondingsphinx.ext.autodoc
directive, but can be customized with templates.The sphinx-autogen script is also able to generate "stub" files from command line.
- .. autosummary::¶
それぞれのアイテムごとに、ドキュメントされたアイテムとblurb(docstringの最初の文)を含むテーブルを挿入します。
The
autosummary
directive can also optionally serve as atoctree
entry for the included items. Optionally, stub.rst
files for these items can also be automatically generated whenautosummary_generate
is True.サンプル:
.. currentmodule:: sphinx .. autosummary:: environment.BuildEnvironment util.relative_uri
これは以下のようなテーブルを作成します:
ReSTファイルが翻訳される環境。
util.relative_uri
(base, to)base
からto
に対する相対URL。autosummaryは、
autodoc
が行っているのと同様に、autodoc-process-docstring
イベントと、autodoc-process-signature
イベントをフックすることで、 docstringとシグニチャの前処理を行います。オプション
- :toctree: optional directory name¶
autosummary
テーブルをtoctree
のエントリーと同様に提供したい場合には、toctree
オプションを使って以下のようにします:.. autosummary:: :toctree: DIRNAME sphinx.environment.BuildEnvironment sphinx.util.relative_uri
toctree
オプションは、このディレクティブに含まれるエントリーのリストに対するスタブのページを作成する、 sphinx-autogen スクリプトにも伝えられます。このオプションは、ディレクトリ名を引数として受け取ります。デフォルトでは sphinx-autogen はこのディレクトリに出力します。もしも引数が与えられなかった場合には、そのディレクティブが含まれているファイルがある、同じディレクトリに出力します。Added in version 0.6.
Add a caption to the toctree.
Added in version 3.1.
- :nosignatures:¶
Do not show function signatures in the summary.
Added in version 0.6.
- :template: filename¶
Specify a custom template for rendering the summary. For example,
.. autosummary:: :template: mytemplate.rst sphinx.environment.BuildEnvironment
このサンプルのコードをビルドすると、
templates_path
に含まれる、mytemplate.rst
という名前のテンプレートファイルを使用して、エントリーのすべてのリストのページを生成します。詳しくは テンプレートのカスタマイズ を参照してください。Added in version 1.0.
- :recursive:¶
Generate documents for modules and sub-packages recursively. For example,
.. autosummary:: :recursive: sphinx.environment.BuildEnvironment
Added in version 3.1.
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 documentation
スタブページの自動作成¶
If you do not want to create stub pages with sphinx-autogen, you can also use these config values:
- autosummary_context¶
A dictionary of values to pass into the template engine's context for autosummary stubs files.
Added in version 3.1.
- autosummary_generate¶
Boolean indicating whether to scan all found documents for autosummary directives, and to generate stub pages for each. It is enabled by default.
スタブページを作成すべきドキュメントをリスト表示するのにも使えます。
ディレクティブの
:toctree:
オプションで指定されたディレクトリに新しいファイルを配置します。バージョン 2.3 で変更: Emits
autodoc-skip-member
event asautodoc
does.バージョン 4.0 で変更: Enabled by default.
- autosummary_generate_overwrite¶
If true, autosummary overwrites existing files by generated stub pages. Defaults to true (enabled).
Added in version 3.0.
- autosummary_mock_imports¶
This value contains a list of modules to be mocked up. See
autodoc_mock_imports
for more details. It defaults toautodoc_mock_imports
.Added in version 2.0.
- autosummary_imported_members¶
A boolean flag indicating whether to document classes and functions imported in modules. Default is
False
Added in version 2.1.
バージョン 4.4 で変更: If
autosummary_ignore_module_all
isFalse
, this configuration value is ignored for members listed in__all__
.
- autosummary_ignore_module_all¶
If
False
and a module has the__all__
attribute set, autosummary documents every member listed in__all__
and no others. Default isTrue
Note that if an imported member is listed in
__all__
, it will be documented regardless of the value ofautosummary_imported_members
. To match the behaviour offrom module import *
, setautosummary_ignore_module_all
to False andautosummary_imported_members
to True.Added in version 4.4.
- autosummary_filename_map¶
A dict mapping object names to filenames. This is necessary to avoid filename conflicts where multiple objects have names that are indistinguishable when case is ignored, on file systems where filenames are case-insensitive.
Added in version 3.2.
テンプレートのカスタマイズ¶
Added in version 1.0.
テンプレート のセクションで説明しているのと同じ、Sphinxの標準的なHTMLのJinjaテンプレートを使って、スタブページのテンプレートをカスタマイズできます。ただし、 TemplateBridge
はサポートしていません。
注釈
もしも、スタブのテンプレートをカスタマイズするのに長い時間をかけているということが分かった場合には、autosummaryによる自動生成をやめて、自分でスタブを書いていく方がいいかもしれません。
autosummaryは以下に示すJinjaのテンプレートファイルを使用します:
autosummary/base.rst
-- 代替のテンプレートautosummary/module.rst
-- モジュールのためのテンプレートautosummary/class.rst
-- クラスのためのテンプレートautosummary/function.rst
-- 関数のためのテンプレートautosummary/attribute.rst
-- クラス属性のためのテンプレートautosummary/method.rst
-- クラスメソッドのためのテンプレート
The following variables are available in the templates:
- name¶
ドキュメントの対象となっているオブジェクトの名前です。モジュール名やクラス名の部分は含まれません。
- objname¶
ドキュメント対象となっているオブジェクトの名前です。モジュール名の部分は含まれません。
- fullname¶
ドキュメント対象となっているオブジェクトの名前です。モジュール名、クラス名も含みます。
- objtype¶
Type of the documented object, one of
"module"
,"function"
,"class"
,"method"
,"attribute"
,"data"
,"object"
,"exception"
,"newvarattribute"
,"newtypedata"
,"property"
.
- module¶
ドキュメント対象のオブジェクトが属しているモジュールの名前です。
- class¶
ドキュメント対象のオブジェクトが属すクラスの名前です。メソッドと属性が対象の場合だけ利用できます。
- underline¶
len(full_name) * '='
の実行結果です。代わりにunderline
フィルターを使用してください。
- members¶
モジュールやクラスに属す、すべてのメンバーの名前のリストです。モジュールとクラスが対象の場合のみ利用できます。
- inherited_members¶
クラスから継承されたメンバーすべての名前のリストです。クラスが対象の場合のみ利用できます。
Added in version 1.8.0.
- functions¶
List containing names of "public" functions in the module. Here, "public" means that the name does not start with an underscore. Only available for modules.
- classes¶
モジュールの"公開"クラスの名前を含むリストです。対象がモジュールの場合のみ利用できます。
- exceptions¶
モジュールの"公開"例外クラスの名前を含むリストです。対象がモジュールの場合のみ利用できます。
- methods¶
クラスの"公開"メソッドの名前を含むリストです。対象がクラスの場合のみ利用できます。
- attributes¶
クラス/モジュールの"公開"属性の名前を含むリストです。対象がクラスとモジュールの場合のみ利用できます。
バージョン 3.1 で変更: Attributes of modules are supported.
- modules¶
List containing names of "public" modules in the package. Only available for modules that are packages and the
recursive
option is on.Added in version 3.1.
さらに、次のフィルータらが利用可能です:
- escape(s)¶
RST コンテキストをフォーマットする際に、テキスト内の任意の特殊文字をエスケープするために使用します。例えば、アスタリスクがボールドにすることを防げます。この機能はHTMLエスケープを行うビルトインのJinja escape filter を置き換えます。
- 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
ディレクティブは、スタブページの中でも使用できます。スタブページは、これらのディレクティブを元に生成されます。