sphinx.ext.autodoc --文書文字列を含む文書

この拡張は、あなたが記録しているモジュールを導入し、文書文字列から半自動的に文書を引き込むことができます。

注釈

Sphinx(実際にはSphinxを実行するPythonインタプリタ)にあなたのモジュールを見つけるためには、導入可能でなければなりません。これはモジュールまたはパッケージが上のあるディレクトリに位置しなければならないことを意味します sys.path --調整します。 sys.path それに応じてプロファイル内にあります。

警告

autodoc imports the modules to be documented. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run.

スクリプト(ライブラリモジュールとは反対)を記録した場合、メインルーチンが受けることを確認してください if __name__ == '__main__' 条件

もちろん，これを実現するためには，文書文字列を正しいreStrutiredTextで書かなければならない.そして、文書文字列では、文書で正しく終了するすべての一般的なSphinxタグを使用することができます。この技術は，手書き文書とともに，文書の2つの位置を維持しなければならない苦痛を軽減し，自動生成された純API文書を回避している.

もしあなたが好きなら NumPy あるいは…。 Google 文書文字列パターンを上書きreStrufredTextに設定すれば，有効にすることもできる napoleon 延期する。 napoleon 文書文字列を以前の正しいreStruredTextに変換することができるプリプロセッサです autodoc 処理しています

指令

autodoc provides several directives that are versions of the usual py:module, py:class and so forth. On parsing time, they import the corresponding module and extract the docstring of the given objects, inserting them into the page source under a suitable py:module, py:class etc. directive.

注釈

Just as py:class respects the current py:module, autoclass will also do so. Likewise, automethod will respect the current py:class.

.. automodule::
.. autoclass::
.. autoexception::

モジュール、クラス、または異常を記録する。デフォルトの場合、すべての3つのコマンドは、オブジェクト自体の文書文字列のみを挿入します：

.. autoclass:: Noodle

以下のソースコードが生成される：

.. class:: Noodle

   Noodle's docstring.

Auto“命令は、文書文字列の後(ただし、任意の自動メンバ文書の前に)生成された非自動命令ソースに挿入される自身のコンテンツを含むこともできる。

したがって、以下のように、自動メンバー文書と非自動メンバー文書を混合して使用することもできます。

.. autoclass:: Noodle
   :members: eat, slurp

   .. method:: boil(time=10)

      Boil the noodle *time* minutes.

選択肢と高度な使い方

  • メンバーを自動的に記録したいなら、1つあります members オプション：：

    .. automodule:: noodle
   :members:

    すべてのモジュールメンバ(再帰)が記録され、：

    .. autoclass:: Noodle
   :members:

    すべての非プライベートメンバ関数および属性(すなわち、名前が最初でない関数および属性が記録される _ ）。

    モジュールでは __all__ メンバーを探す時には尊重されます ignore-module-all マークオプション。なし ignore-module-all メンバーの順番も __all__ それがそうです。

    あなたはまた明確なメンバーリストを提供することができます。これらのメンバーだけが記録されます。

    .. autoclass:: Noodle
   :members: eat, slurp

  • もしあなたが members オプション(または以下に説明する他のオプション)はデフォルト値ですので、参照されたい autodoc_default_options それがそうです。

    ちなみに

    否定的な形で 'no-{flag}' Autodoc命令の一つのオプションとして、それを一時的に無効にします。例えば：

    .. automodule:: foo
   :no-undoc-members:

  • 文書文字列のないメンバーは無視されます undoc-members フラグオプション：：

    .. automodule:: noodle
   :members:
   :undoc-members:

  • “個人”のメンバー(すなわち“個人”と命名されたもの _private あるいは…。 __private )は含まれています private-members マークオプションを与えました：

    .. automodule:: noodle
   :members:
   :private-members:

    パラメータとして記録される明示的なメンバ名リストを使用することもできる：

    .. automodule:: noodle
   :members:
   :private-members: _spicy, _garlickly

    バージョン 1.1 で追加.

    バージョン 3.2 で変更: このオプションは今パラメータを受け取ることができます。

  • メンバの文書文字列が含まれていれば :meta private: その中で 情報フィールドリスト それがそうです。例：

    def my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta private:
    """

    バージョン 3.0 で追加.

  • メンバの文書文字列が含まれていれば :meta public: その中で 情報フィールドリスト 次の線で先頭に立っていても例：

    def _my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta public:
    """

    バージョン 3.1 で追加.

  • 変数メンバの文書文字列が含まれていれば :meta hide-value: その中で 情報フィールドリスト それがそうです。例：

    var1 = None  #: :meta hide-value:

    バージョン 3.5 で追加.

  • Python“特別な”メンバー(すなわち名前は __special__ )は含まれています special-members マークオプションを与えました：

    .. autoclass:: my.Class
   :members:
   :private-members:
   :special-members:

    クラスの“プライベート”と“特殊”のメンバーを記録する。

    バージョン 1.1 で追加.

    バージョン 1.2 で変更: このオプションは現在パラメータ，すなわち記録する特殊なメンバを受け取ることができる.

  • クラスや例外については，すべてのメンバを記録する際には，与えられない限り，基本クラスから継承されたメンバは省略する. inherited-members 選択肢は、それを除いて members **

    .. autoclass:: Noodle
   :members:
   :inherited-members:

    これは undoc-members 記録するには、以下の操作を実行してください all クラスまたはモジュールの利用可能なメンバ。

    それは先祖類がそれから継承された会員たちを記録しないようにすることができる。デフォルトの場合、 object クラスには文書記録がない.すべての人に見せるためには None オプションに追加します。

    例えばあなたのクラスが Foo 派生自. list クラス、そしてあなたは記録したくありません list.__len__() オプションを指定する必要があります :inherited-members: list Listクラスの特殊なメンバを避けるために。

    Another example; If your class Foo has __str__ special method and autodoc directive has both inherited-members and special-members, __str__ will be documented as in the past, but other special method that are not implemented in your class Foo.

    なお、継承されたメンバがその文書文字列からRESTフォーマットのモジュールでない場合、これはタグ付け誤りを招く。

    バージョン 0.3 で追加.

    バージョン 3.0 で変更: これは祖先クラス名をパラメータとしている.

  • 従来の構文を使用して、明示的に記録された呼び出し可能なオブジェクト(関数、方法、クラス)の署名をカバーすることができ、この構文は、リフレクションから取得された署名をカバーする。

    .. autoclass:: Noodle(type)

   .. automethod:: eat(persona)

    この方法からの署名が装飾子によって隠されている場合、これは有用である。

    バージョン 0.4 で追加.

  • The automodule, autoclass and autoexception directives also support a flag option called show-inheritance. When given, a list of base classes will be inserted just below the class signature (when used with automodule, this will be inserted for every class that is documented in the module).

    バージョン 0.4 で追加.

  • すべてのautocコマンドはサポートされています noindex 標準と同じ効果を持つマークオプション py:function 等コマンド：レコードのオブジェクト(およびすべての自動レコードのメンバ)にインデックス項目を生成しない.

    バージョン 0.4 で追加.

  • automodule also recognizes the synopsis, platform and deprecated options that the standard py:module directive supports.

    バージョン 0.5 で追加.

  • automodule そして autoclass 一つもあります member-order 書き換えに使用可能なオプション autodoc_member_order 指示は一つしかありません。

    バージョン 0.6 で追加.

  • メンバー文書をサポートするコマンドもあります exclude-members すべてのメンバを記録する場合、オプションは、文書から単一のメンバ名を除外するために使用されてもよい。

    バージョン 0.6 で追加.

  • ある automodule 指令と members オプションセット、そのモジュールメンバのみ __module__ 属性は与えられたモジュール名と同じである automodule 記録されていますこれは，導入したクラスや関数の文書記述を防ぐためである.設ける imported-members この行動を防止してすべての利用可能なメンバーを記録する場合は、このオプションを選択してください。導入モジュールには属性文書が現在のモジュールのソースファイルを解析することで発見されるため，導入モジュールには属性は記録されないことに注意されたい.

    バージョン 1.2 で追加.

  • モジュールリストの追加 autodoc_mock_imports 生成時に何らかの外部依存項が導入不可能な場合に生成過程を停止するように，導入誤りを防ぐ.

    バージョン 1.3 で追加.

  • Autoc拡張へのヒントとして、 :: モジュール名とオブジェクト名の間のセパレータは，モジュール名が明確でない場合にautocに正しいモジュール名を知ってもらうためである.**

    .. autoclass:: module.name::Noodle
.. autofunction::
.. autodecorator::
.. autodata::
.. automethod::
.. autoattribute::

彼らの動作原理は autoclass など，自動メンバ文書のためのオプションは提供されていない.

autodata そして autoattribute 支持する. annotation 選択します。このオプションは変数値の表示方式を制御する.パラメータがない場合に指定された場合、変数の名前のみが印刷され、その値は表示されない：

.. autodata:: CD_DRIVE
   :annotation:

オプションがパラメータを指定した場合、変数としての値を名前の後に印刷する：

.. autodata:: CD_DRIVE
   :annotation: = your CD device name

デフォルトの場合、なければ annotation オプションの場合、Sphinxは変数の値を取得し、名前の後に印刷しようと試みる。

♪the no-value 選択肢は空白の代わりに使うことができます annotation 値を表示せずにタイプ提示を表示するには、以下の操作を実行してください。

.. autodata:: CD_DRIVE
   :no-value:

もしこの2つが annotation そして no-value オプションを使用して、 no-value 効果がありません。

モジュールデータのメンバやクラス属性については，文書を特殊なフォーマットのアノテーションに入れることができる(使用する). #: コメントを始めるだけでなく # )、または文書文字列で その後 定義する。注釈は自分の行にある必要がある その前に 定義や代入の直後に 同じ線の上で それがそうです。後者の形式は1行に限定される.

これは，以下のクラス定義において，すべての属性を自動的に記録できることを意味する.

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

バージョン 0.6 で変更: autodata そして autoattribute 今は文書文字列を抽出することができる.

バージョン 1.1 で変更: 現在，割当て後の同一行で備考文書を使用することを許可している.

バージョン 1.2 で変更: autodata そして autoattribute Vbl.ある annotation 選択します。

バージョン 2.0 で変更: autodecorator 入れました。

バージョン 3.4 で変更: autodata そして autoattribute 今は1つあります no-value 選択します。

注釈

修飾関数や方法を記録する場合は、autocはモジュールを導入して検査することを覚えてください __doc__ 関数またはメソッドの属性を与える.これは装飾器が他の装飾関数で装飾関数を置き換えると、元のものをコピーしなければならないことを意味します。 __doc__ 新しい機能です。

配置

また、以下の構成値を設定することができます。

autoclass_content

この値は，どのような内容を挿入するかを選択する. autoclass 指令する。可能な値は：

"class"

クラスの文書文字列のみを挿入する.これはデフォルト設定です。あなたはまだ記録することができます __init__ 単独の方法として使用する automethod あるいは…。 members 選択権. autoclass それがそうです。

"both"

クラスの学生と __init__ メソッドの文書文字列を連結して挿入する.

"init"

唯 __init__ メソッドの文書文字列が挿入される.

バージョン 0.3 で追加.

類がなければ __init__ 方法、あるいは __init__ 方法のdocstringは空であるが，このようなものは __new__ メソッドの文書文字列は，それに変更する.

バージョン 1.4 で追加.

autodoc_member_order

この値は，自動記録されたメンバがアルファベット順にソートされるかどうかを選択する(値 'alphabetical' )、メンバータイプ別(値) 'groupwise' )またはソース順(値) 'bysource' ）。デフォルト値はアルファベット順である.

ソースコード順序については、モジュールはソースコードを含むPythonモジュールでなければならないことに注意されたい。

バージョン 0.6 で追加.

バージョン 1.0 で変更: 支持する. 'bysource' それがそうです。

autodoc_default_flags

This value is a list of autodoc directive flags that should be automatically applied to all autodoc directives. The supported flags are 'members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance', 'ignore-module-all' and 'exclude-members'.

バージョン 1.0 で追加.

バージョン 1.8 で非推奨: 統合して autodoc_default_options それがそうです。

autodoc_default_options

Autodocコマンドのデフォルトオプション。これらは自動的にすべてのautoc命令に適用される.それはオプション名を値にマッピングする辞書でなければならない。例えば：

autodoc_default_options = {
    'members': 'var1, var2',
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

設ける None あるいは…。 True この値に設定することは、命令にのみオプション名を提供することに等価である。

The supported options are 'members', 'member-order', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance', 'ignore-module-all', 'imported-members' and 'exclude-members'.

バージョン 1.8 で追加.

バージョン 2.0 で変更: 受け入れる True 一つの価値として。

バージョン 2.1 で変更: 増列する. 'imported-members' それがそうです。

autodoc_docstring_signature

Cモジュールから導入された関数をリフレクションできないため，このような関数の署名を自動的に決定することはできない.しかし，関数文書文字列の1行目に署名を置くことはよく用いられる約束である.

このブール値を設定すれば True (これはデフォルト設定である)、autocは、署名のように見える場合、その行を署名として使用し、文書文字列の内容から削除するために、文書文字列の第1の行を参照する。

署名行が逆スラッシュで終わると、autocは、この関数に複数の署名があると考え、文書文字列の次の行を見る。これは再負荷関数に非常に有用である.

バージョン 1.1 で追加.

バージョン 3.1 で変更: 再ロード署名をサポートします

autodoc_mock_imports

この値はシミュレーションするモジュールリストを含む.これは，ある外部依存項が構築時に構築過程を満たして中断できない場合に有用である.依存項自体のルートパッケージのみを指定することができますが、サブモジュールを省略することができます。

autodoc_mock_imports = ["django"]

全てをシミュレートします django 小包です。

バージョン 1.3 で追加.

バージョン 1.6 で変更: この構成値は，シミュレーションすべきトップモジュールのみを宣言する必要がある.

autodoc_typehints

この値は，タイプ提示をどのように表すかを制御する.この設定は、次の値を採用する。

  • 'signature' --タイププロンプトをその署名(デフォルト)として表示します。

  • 'description' --タイププロンプトを関数または方法の内容として表示する

  • 'none' --キー入力プロンプトは表示されません

バージョン 2.1 で追加.

バージョン 3.0 で追加: 新しいオプション 'description' 追加されました。

autodoc_type_aliases

ユーザのための辞書 `type aliases`_ _、タイプ名を完全に限定されたオブジェクト名にマッピングします。これは，文書中で計算されないタイプの別名を保存するために用いられる.黙認して空にする ({{}} ）。

タイプ別名はあなたのプログラムでのみ有効です `Postponed Evaluation of Annotations (PEP 563)`_ _要素通過 from __future__ import annotations それがそうです。

例えば、いくつかのコード使用タイプ別名：

from __future__ import annotations

AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

def f() -> AliasType:
    ...

もし autodoc_type_aliases 設定されていなければ，autocはこのコードから内部タグを生成し，以下のようになる.

.. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

   ...

もしあなたが設定したら autodoc_type_aliases として {{'AliasType': 'your.module.AliasType'}} これは，内部で以下の文書を生成する.

.. py:function:: f() -> your.module.AliasType:

   ...

バージョン 3.3 で追加.

autodoc_warningiserror

この値制御 sphinx-build -W モジュールを導入している間.もし False 導入したモジュールが警告を発すると，autocはそのエラーを強制的に抑制する.デフォルトの場合、 True それがそうです。

autodoc_inherit_docstrings

この値は文書文字列継承を制御する.Trueに設定されている場合、クラスまたはメソッドの文書文字列(明示的に設定されていない場合)は親レベルから継承される。

黙認する. True それがそうです。

バージョン 1.7 で追加.

suppress_warnings

autodoc 以下のように警告メッセージを抑制することをサポートする suppress_warnings それがそうです。これはまた、以下の警告タイプを許可する。

  • 自動ドッキング.

  • autodoc.import_object

文書文字列前処理

Autodocは、以下の追加イベントを提供します。

autodoc-process-docstring(app, what, name, obj, options, lines)

バージョン 0.4 で追加.

Autocが文書文字列を読み込んで処理する場合に発行される. 線.線 イベントハンドラが修正可能な文字列リストである処理済み文書文字列の行である 位置につけ！ Sphinxが出力に入力する内容を変更します。

パラメータ

  • app -- Sphinxアプリケーションオブジェクト

  • what -- the type of the object which the docstring belongs to (one of "module", "class", "exception", "function", "method", "attribute")

  • name -- 対象の完全限定名

  • obj -- 対象自体が

  • options -- the options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and noindex that are true if the flag option of same name was given to the auto directive

  • lines -- 文書文字列の行は、上記を参照されたい

autodoc-before-process-signature(app, obj, bound_method)

バージョン 2.4 で追加.

Autodocフォーマット対象署名の前に発行する.イベントハンドラは，その署名を変更するためにオブジェクトを修正することができる.

パラメータ

  • app -- Sphinxアプリケーションオブジェクト

  • obj -- 対象自体が

  • bound_method -- ブール値は、オブジェクトが束縛されているかどうかを示す

autodoc-process-signature(app, what, name, obj, options, signature, return_annotation)

バージョン 0.5 で追加.

Autocがフォーマットされたオブジェクトの署名を発行する.イベントハンドラは新しいタプルを返すことができる (signature, return_annotation) Sphinxが出力に入力する内容を変更します。

パラメータ

  • app -- Sphinxアプリケーションオブジェクト

  • what -- the type of the object which the docstring belongs to (one of "module", "class", "exception", "function", "method", "attribute")

  • name -- 対象の完全限定名

  • obj -- 対象自体が

  • options -- the options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and noindex that are true if the flag option of same name was given to the auto directive

  • signature -- 関数署名、フォーマットは文字列 "(parameter_1, parameter_2)" あるいは、あるいは None もしリフレクションが成功しなかったら、指示に署名が指定されていない。

  • return_annotation -- 関数は注釈を以下の形式の文字列に返す " -> annotation" あるいは、あるいは None 注釈が戻っていなければ

♪the sphinx.ext.autodoc モジュールは、イベントで一般的に使用される文書文字列処理に工場関数を提供する autodoc-process-docstring ：

sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: Optional[str] = None) → Callable[ソース]

最初の削除に戻ります。 pre 最後です。 post 各文書文字列の行。もし what 1つの種類の文書文字列のみがある文字列列である what 処理されます。

このように使用する(例えば、 setup() 機能しています conf.py )：

from sphinx.ext.autodoc import cut_lines
app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))

これは代わりに使うべきだ automodule_skip_lines それがそうです。

sphinx.ext.autodoc.between(marker: str, what: Optional[Sequence[str]] = None, keepempty: bool = False, exclude: bool = False) → Callable[ソース]

保留しているか保存しているかのいずれかのリスニングプログラムに戻ります 排除する Trueで一致する行間の行を除外するかどうか 標識物 正規表現.一致する行がなければ，生成された文書文字列は空となるため，何の変更も行わない. 空に保つ 本当です。

もし what 1つの種類の文書文字列のみがある文字列列である what 処理されます。

メンバーを飛び越している

Autodocは、ユーザが、メンバを文書に含めるべきかどうかを決定するために、以下のイベントを使用してカスタム方法を定義することを可能にする。

autodoc-skip-member(app, what, name, obj, skip, options)

バージョン 0.5 で追加.

Autocがメンバを文書に含めるべきかどうかを決定しなければならない場合.ハンドラが戻ってきた場合は，そのメンバを除外する. True それがそうです。処理プログラムが戻ってくると、それが含まれています False それがそうです。

複数の有効な拡張処理がある場合 autodoc-skip-member イベントの場合，autocはハンドラを用いて返された最初の非`Noneﾟ`‘の値を返す.処理プログラムは戻るべきです None Autocや他の有効な拡張のスキップ行為に戻す.

パラメータ

  • app -- Sphinxアプリケーションオブジェクト

  • what -- the type of the object which the docstring belongs to (one of "module", "class", "exception", "function", "method", "attribute")

  • name -- 対象の完全限定名

  • obj -- 対象自体が

  • skip -- ユーザハンドラが決定を書き換えなければ，autocがそのメンバをスキップするかどうかを示すブール値である.

  • options -- the options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and noindex that are true if the flag option of same name was given to the auto directive