sphinx.ext.autosummary --自動文書要約の生成

バージョン 0.6 で追加.

この拡張生成関数/メソッド/属性要約リストは，Epydocや他のAPI文書生成ツールの出力と類似している.あなたの文書文字列が長くて詳細な場合、これは特に有用であり、各文書を別個のページに置くことで読みやすくなります。

♪the sphinx.ext.autosummary Extensionは2つの部分で実現される：

  1. ある autosummary 文書項目へのリンクと、文書文字列から抽出された短い要約フォーマット返信情報とを含む要約リストを生成するための命令。

  2. オプションとして、利便性スクリプト sphinx-autogen あるいは新しいのです autosummary_generate 構成値は、リストされたエントリのための短い“スタブ”ファイルを生成するために使用することができる autosummary 指令する。デフォルトの場合、これらのファイルには対応するもののみが含まれています sphinx.ext.autodoc コマンドは，テンプレートを用いてカスタマイズすることができる.

.. autosummary::

記録された項目へのリンクを含み，項目ごとに短い要約プロファイル(文書文字列の第1文)を挿入するテーブルを挿入する.

♪the autosummary 指示はまた選択的に機能することができます toctree 項目を含む項目。オプションの控え .rst 以下の場合には，これらの項目のファイルを自動生成することも可能である. autosummary_generate はい。 True それがそうです。

例えば、：：

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

以下に示す表を生成する.

environment.BuildEnvironment \(アプリ)

RESTファイルを変換する環境。

util.relative_uri \(BASE，TO)

戻りから相対URL base 至る to それがそうです。

文書文字列と署名を自動的にまとめて前処理する autodoc-process-docstring そして autodoc-process-signature フックをする. autodoc それがそうです。

Options

  • もしあなたが望むなら autosummary 時計は同時に機能しています toctree 項目、ご利用ください toctree オプション、例えば：

    .. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

    ♪the toctree 選択肢はまだ sphinx-autogen 本コマンドに列挙されたエントリのためのスタブページのスクリプトを生成すべきである.このオプションは、パラメータとしてディレクトリ名を受け取ります。 sphinx-autogen デフォルトでは、その出力をこのディレクトリに置きます。パラメータが与えられていなければ，その命令を含むファイルと同じディレクトリに出力する.

    ご利用いただけます caption Toctreeにタイトルのオプションを提供する.

    バージョン 3.1 で追加: タイトルオプションが追加されました。

  • もしあなたが欲しくなければ autosummary リストに関数署名を表示する場合は、含めてください nosignatures オプション：：

    .. autosummary::
   :nosignatures:

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

  • 属性はカスタムテンプレートを指定する. template 選択します。例えば、：：

    .. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment

    テンプレートを使用します mytemplate.rst あなたの templates_path リストされたすべてのエントリのためのページを生成します。見 Customizing templates 下です。

    バージョン 1.0 で追加.

  • ご指定いただけます recursive モジュールやサブルーチン文書を再帰的に生成するためのオプション.無効にすると黙認しています。例えば、：：

    .. autosummary::
   :recursive:

   sphinx.environment.BuildEnvironment

    バージョン 3.1 で追加.

sphinx-autogen --Autodocスタブページの生成

♪the sphinx-autogen スクリプトは，中に含まれる項目のスタブ文書ページを容易に生成するために用いることができる. autosummary リストです。

例えば、コマンド：：

$ sphinx-autogen -o generated *.rst

全てを読み取ります autosummary 中の表 *.rst 有す :toctree: エントリセットを選択し，ディレクトリに対応するスタブページを出力する. generated すべて記録された項目です。デフォルトの場合、生成されたページは、以下の形式のテキストを含む：

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

.. autofunction:: sphinx.util.relative_uri

もし -o オプション、スクリプトは出力ファイルを置きます :toctree: 選択します。

詳細についてはご参照ください sphinx-autogen documentation

スタブページを自動生成する

スタブページの作成をご利用になりたくない場合は sphinx-autogen また、以下の構成値を使用することができます。

autosummary_context

テンプレートエンジンコンテキストに渡された値辞書は、スタブファイルを自動的にまとめるために使用される。

バージョン 3.1 で追加.

autosummary_generate

見つかったすべての文書をスキャンして自動集約コマンドを探すかどうかを指示し、各コマンドについてスタブページのブール値を生成する。デフォルトでは無効状態になります。

スタブページを生成すべき文書リストであってもよい.

新しい書類は :toctree: 指示のオプション。

バージョン 2.3 で変更: 排出する. autodoc-skip-member 活動として autodoc その通りです。

autosummary_generate_overwrite

Trueであれば，生成されたスタブページで既存ファイルを自動的にまとめる.デフォルトでtrue(有効になった)とする.

バージョン 3.0 で追加.

autosummary_mock_imports

この値はシミュレーションするモジュールリストを含む.見 autodoc_mock_imports もっと細かいことを知っています。デフォルト値は autodoc_mock_imports それがそうです。

バージョン 2.0 で追加.

autosummary_imported_members

1つのブールフラグは，モジュールに導入されたクラスや関数を記録するかどうかを示す.デフォルト値は False

バージョン 2.1 で追加.

autosummary_filename_map

オブジェクト名をファイル名のDICTにマッピングする.文書名が大文字を区別しない文書システムでは，大文字を無視した場合に複数のオブジェクトの名前が区別できない場合には，文書名の衝突を避けるために必要である.

バージョン 3.2 で追加.

カスタムテンプレート

バージョン 1.0 で追加.

スタブページテンプレートをカスタマイズすることができます。方法はHTML JJJAテンプレートと類似していますので、参照してください。 テンプレート化する それがそうです。 (TemplateBridge 支持されない。)

注釈

スタブテンプレートを裁断するのに時間がかかっていることを発見すれば，カスタム記述文書を作成した方が良いことを示している可能性がある.

自動まとめて以下のJJJAテンプレートファイルを使用します：

  • autosummary/base.rst --予備テンプレート

  • autosummary/module.rst --モジュールテンプレート

  • autosummary/class.rst --クラステンプレート

  • autosummary/function.rst --関数テンプレート

  • autosummary/attribute.rst --クラス属性テンプレート

  • autosummary/method.rst --クラスメソッドテンプレート

テンプレートには以下の変数が提供される：

name

文書オブジェクトの名前は，モジュールやクラス部品は含まれていない.

objname

記録されたオブジェクトの名前は，モジュール部分は含まれていない.

fullname

文書オブジェクトのフルネームは，モジュールとクラス部品を含む.

module

レコードのオブジェクトが属するモジュールの名前.

class

文書オブジェクトが属するクラスの名前.メソッドと属性にのみ適用される.

underline

以下を含む文字列 len(full_name) * '=' それがそうです。使用 underline 代わりにフィルターがあります

members

モジュールまたはクラスを含むすべてのメンバ名のリスト。モジュールとクラスにのみ適用される.

inherited_members

クラスを含むすべての継承メンバの名前のリスト.クラスにのみ適用されます。

バージョン 1.8.0 で追加.

functions

モジュール中の“public”関数名のリストを含む.ここで，“public”とは，名称が以下のように下線を引かずに始まることを意味する.モジュールにのみ適用される.

classes

モジュール中の“public”クラス名のリストを含む.モジュールにのみ適用される.

exceptions

モジュール中の“共通”例外名のリストを含む.モジュールにのみ適用される.

methods

クラス中の“public”メソッド名のリストを含む.クラスにのみ適用されます。

attributes

クラス/モジュールにおける“public”属性名のリストを含む.クラスとモジュールにのみ適用される.

バージョン 3.1 で変更: モジュール属性をサポートします。

modules

パケット中の“共通”モジュール名のリストが含まれています。ソフトウェアパッケージとしてのみ適用可能なモジュールと recursive オプションが開きました。

バージョン 3.1 で追加.

また，以下のフィルタを用いることも可能である.

escape(s)

RSTコンテキストで使用されるテキスト中の任意の特別な文字をフォーマットすることを転義する。例えば、これは星号が物事を大胆にすることを防ぐことができる。これは内蔵の金佳の代わりに escape filter Html変換を行うことができます

underline(s, line='=')

1つのテキストに見出し下線を付加する.

例えば、 {{{{ fullname | escape | underline }}}} ページタイトルの生成に適用する.

注釈

ご利用いただけます autosummary 指令する。スタブページもこれらのコマンドに基づいて生成される.