sphinx.ext.autodoc – docstringからドキュメントをインクルードする

この拡張機能は、ドキュメント化するモジュールをインポートし、docstringからドキュメントを半自動的に取り込むことができます。

警告

autodoc は、ドキュメント化されるモジュールを**インポート**します。モジュールにインポート時に副作用がある場合、sphinx-build の実行時に autodoc によってこれらが実行されます。

（ライブラリモジュールとは対照的に）スクリプトをドキュメント化する場合は、メインルーチンが if __name__ == '__main__' 条件で保護されていることを確認してください。

これが機能するためには、docstringが正しいreStructuredTextで記述されている必要があります。docstringでは通常のSphinxマークアップをすべて使用でき、ドキュメントに正しく反映されます。手書きのドキュメントと組み合わせることで、ドキュメントの2つの場所を保守する必要がなくなり、同時に自動生成されたように見える純粋なAPIドキュメントを回避できます。

reStructuredTextよりも、NumPy または Google スタイルのdocstringを優先する場合は、napoleon 拡張機能を有効にすることもできます。napoleon は、autodoc が処理する前に、docstringを正しいreStructuredTextに変換するプリプロセッサです。

はじめに

セットアップ

'sphinx.ext.autodoc' を conf.py の extensions に追加して、プラグインを有効にします。

extensions = [
    ...
    'sphinx.ext.autodoc',
]

コードがインポートできることの確認

autodoc は、モジュールをインポートした後、イントロスペクションによってコードとdocstringを分析します。インポートが機能するには、モジュールがSphinxによって検出されること、および依存関係が解決されることを確認する必要があります（モジュールが import foo を実行するが、foo がSphinxが実行されるPython環境で使用できない場合、モジュールのインポートは失敗します）。

これを確実にするには、2つの方法があります。

  1. パッケージとSphinxを含む環境を使用します。これは、たとえば、ローカルの開発環境（編集可能なインストールあり）や、SphinxとパッケージをインストールするCI環境などです。通常のインストールプロセスにより、パッケージがSphinxによって検出され、すべての依存関係が利用可能になります。

  2. または、ソースから直接操作できるようにSphinxの実行をパッチすることもできます。たとえば、ソースのチェックアウトからSphinxビルドを実行できるようにしたい場合です。

    • ソースのフォルダを含めるように、Sphinxの conf.py で sys.path をパッチします。たとえば、リポジトリ構造が doc/conf.py で、パッケージが src/mypackage にある場合は、次を追加する必要があります。

      sys.path.insert(0, os.path.abspath('../src'))

      conf.py に。

    • 不足している依存関係に対処するには、autodoc_mock_imports で不足しているモジュールを指定します。

使い方

これで、ディレクティブ を使用して、関数、クラス、モジュールなどのPythonコード要素のフォーマットされたドキュメントを追加できます。たとえば、ソースファイルから署名とdocstringを読み取って、関数 io.open() をドキュメント化するには、次のように記述します。

.. autofunction:: io.open

また、自動ディレクティブのメンバーオプションを使用して、クラス全体またはモジュール全体を自動的にドキュメント化することもできます。例：

.. automodule:: io
   :members:

ディレクティブ

autodoc は、通常の py:module、py:class などのバージョンであるいくつかのディレクティブを提供します。解析時に、対応するモジュールをインポートし、指定されたオブジェクトのdocstringを抽出して、適切な py:module、py:class などのディレクティブの下にページソースに挿入します。

注記

py:classが現在のpy:moduleを尊重するのと同様に、autoclassも同様に動作します。同様に、automethodは現在のpy:classを尊重します。

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

モジュール、クラス、または例外をドキュメント化します。これら3つのディレクティブは、デフォルトではオブジェクト自体のドックストリングのみを挿入します。

.. autoclass:: Noodle

次のようなソースを生成します。

.. class:: Noodle

   Noodle's docstring.

「auto」ディレクティブは、独自のコンテンツを含むこともできます。これは、ドックストリングの後（ただし、自動メンバードキュメントの前）に、結果として得られる非autoディレクティブソースに挿入されます。

したがって、次のように、自動と非自動のメンバードキュメントを混在させることもできます。

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

   .. method:: boil(time=10)

      Boil the noodle *time* minutes.

オプション

:members: (値なし、またはコンマ区切りのリスト)

設定されている場合、autodocはターゲットモジュール、クラス、または例外のメンバーのドキュメントを生成します。

例:

.. automodule:: noodle
   :members:

これにより、すべてのモジュールメンバー（再帰的に）がドキュメント化され、

.. autoclass:: Noodle
   :members:

これにより、すべてのクラスメンバーのメソッドとプロパティがドキュメント化されます。

デフォルトでは、autodocは、プライベート、ドックストリングがない、スーパークラスから継承された、または特別なメンバーであるメンバーのドキュメントは生成しません。

モジュールの場合、ignore-module-allフラグオプションを指定しない限り、メンバーを探す際に__all__が尊重されます。ignore-module-allがない場合、メンバーの順序も__all__の順序になります。

明示的なメンバーのリストを指定することもできます。その場合、これらのメンバーのみがドキュメント化されます。

.. autoclass:: Noodle
   :members: eat, slurp
:undoc-members: (値なし)

設定されている場合、autodocはドックストリングがないメンバーのドキュメントも生成します。

.. automodule:: noodle
   :members:
   :undoc-members:
:private-members: (値なし、またはコンマ区切りのリスト)

設定されている場合、autodocはプライベートメンバー（つまり、_privateまたは__privateのような名前のもの）のドキュメントも生成します。

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

引数としてドキュメント化するメンバー名の明示的なリストを受け取ることもできます。

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

バージョン 1.1 で追加。

バージョン 3.2 で変更: オプションは引数を受け取ることができるようになりました。

:special-members: (値なし、またはコンマ区切りのリスト)

設定されている場合、autodocは特別なメンバー（つまり、__special__のような名前のもの）のドキュメントも生成します。

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

引数としてドキュメント化するメンバー名の明示的なリストを受け取ることもできます。

.. autoclass:: my.Class
   :members:
   :special-members: __init__, __name__

バージョン 1.1 で追加。

バージョン 1.2 で変更: オプションは引数を受け取ることができるようになりました

オプションと高度な使い方

  • membersオプション（または以下に説明するその他のオプション）をデフォルトにしたい場合は、autodoc_default_optionsを参照してください。

    ヒント

    autodocディレクティブのオプションとして、否定形である'no-flag'を使用して、一時的に無効にすることができます。例:

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

    ヒント

    autodocディレクティブオプションを使用して、リストを入力として受け取るデフォルトオプションを一時的にオーバーライドまたは拡張できます。例:

    .. autoclass:: Noodle
   :members: eat
   :private-members: +_spicy, _garlickly

    バージョン 3.5 で変更: デフォルトオプションを一時的にオーバーライドまたは拡張できるようになりました。

  • autodocは、メンバーのドックストリングに情報フィールドリストに:meta private:が含まれている場合、そのメンバーをプライベートと見なします。例:

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

    :meta private:
    """

    バージョン 3.0 で追加。

  • autodocは、アンダースコアで始まる場合でも、ドックストリングに情報フィールドリストに:meta public:が含まれている場合、そのメンバーをパブリックと見なします。例:

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

    :meta public:
    """

    バージョン 3.1 で追加。

  • autodocは、変数のドックストリングに情報フィールドリストに:meta hide-value:が含まれている場合、デフォルト値を持たないと見なします。例:

    var1 = None  #: :meta hide-value:

    バージョン 3.5 で追加。

  • クラスと例外の場合、すべてのメンバーをドキュメント化する場合、基本クラスから継承されたメンバーは、membersに加えてinherited-membersオプションを指定しない限り、除外されます。

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

    これは、undoc-membersと組み合わせて、クラスまたはモジュールのすべての利用可能なメンバーをドキュメント化できます。

    継承されたメンバーをドキュメント化しない祖先クラスを受け取ることができます。デフォルトでは、objectクラスのメンバーはドキュメント化されません。すべて表示するには、オプションにNoneを指定します。

    例: クラスFooがlistクラスから派生していて、list.__len__()をドキュメント化したくない場合は、リストクラスの特殊メンバーを避けるために、オプション:inherited-members: listを指定する必要があります。

    別の例: クラスFooに__str__特殊メソッドがあり、autodocディレクティブにinherited-membersとspecial-membersの両方がある場合、__str__は過去と同じようにドキュメント化されますが、クラスFooに実装されていない他の特殊メソッドはドキュメント化されません。

    v5.0以降、祖先クラスのコンマ区切りリストを受け取ることができます。これにより、automoduleディレクティブにオプションを指定することにより、モジュール上の複数のクラスの継承されたメンバーを一度に抑制できます。

    注: 継承されたメンバーが、ドックストリングがreStructuredText形式でないモジュールからのものである場合、これによりマークアップエラーが発生します。

    バージョン 0.3 で追加。

    バージョン 3.0 で変更: 引数として祖先クラス名を受け取るようになりました。

    バージョン 5.0 で変更: 祖先クラス名のコンマ区切りリストを受け取るようになりました。

  • イントロスペクションから得られたシグネチャをオーバーライドする通常の構文を使用して、明示的にドキュメント化された呼び出し可能オブジェクト（関数、メソッド、クラス）のシグネチャをオーバーライドすることが可能です。

    .. autoclass:: Noodle(type)

   .. automethod:: eat(persona)

    これは、メソッドからのシグネチャがデコレータによって隠されている場合に役立ちます。

    バージョン 0.4 で追加。

  • automodule、autoclass、およびautoexceptionディレクティブは、show-inheritanceというフラグオプションもサポートしています。指定すると、基本クラスのリストがクラスシグネチャのすぐ下に挿入されます（automoduleで使用した場合、これはモジュールでドキュメント化されているすべてのクラスに対して挿入されます）。

    バージョン 0.4 で追加。

  • すべてのautodocディレクティブは、標準のpy:functionなどのディレクティブと同じ効果を持つno-indexフラグオプションをサポートしています。ドキュメント化されたオブジェクト（およびすべての自動ドキュメント化されたメンバー）に対してインデックスエントリは生成されません。

    バージョン 0.4 で追加。

  • automodule は、標準の py:module ディレクティブがサポートする synopsis、platform、deprecated オプションも認識します。

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

  • automodule と autoclass には、autodoc_member_order のグローバル値をディレクティブごとにオーバーライドするために使用できる member-order オプションもあります。

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

  • メンバーのドキュメントをサポートするディレクティブには、すべてのメンバーをドキュメント化する場合に、ドキュメントから単一のメンバー名を除外するために使用できる exclude-members オプションもあります。

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

  • members オプションが設定された automodule ディレクティブでは、__module__ 属性が automodule に指定されたモジュール名と等しいモジュールメンバーのみがドキュメント化されます。これは、インポートされたクラスや関数のドキュメント化を防ぐためです。この動作を回避し、利用可能なすべてのメンバーをドキュメント化する場合は、imported-members オプションを設定してください。インポートされたモジュールからの属性は、属性ドキュメントが現在のモジュールのソースファイルを解析することで発見されるため、ドキュメント化されないことに注意してください。

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

  • autodoc_mock_imports にモジュールリストを追加して、ビルド時に一部の外部依存関係がインポートできない場合に、インポートエラーによってビルドプロセスが中断されるのを防ぎます。

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

  • autodoc 拡張機能へのヒントとして、モジュール名とオブジェクト名の間に :: セパレーターを配置して、autodoc に曖昧な場合の正しいモジュール名を知らせることができます。

    .. autoclass:: module.name::Noodle

  • autoclass は、autoclass_content のグローバル値をオーバーライドするために使用できる class-doc-from オプションも認識します。

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

.. autofunction::
.. autodecorator::
.. autodata::
.. automethod::
.. autoattribute::
.. autoproperty::

これらは autoclass などとまったく同じように機能しますが、自動メンバードキュメントに使用されるオプションは提供しません。

autodata と autoattribute は annotation オプションをサポートします。このオプションは、変数の値をどのように表示するかを制御します。引数なしで指定した場合、変数の名前のみが出力され、その値は表示されません。

.. autodata:: CD_DRIVE
   :annotation:

引数を指定してオプションを指定した場合、変数の値として名前の後に出力されます。

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

デフォルトでは、annotation オプションなしで、Sphinx は変数の値を取得して、名前の後に出力しようとします。

no-value オプションは、空白の annotation の代わりに、型ヒントを表示するが値を表示しないために使用できます。

.. autodata:: CD_DRIVE
   :no-value:

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 が docstring を抽出できるようになりました。

バージョン 1.1 で変更: コメントドキュメントを、割り当て後の同じ行で許可するようになりました。

バージョン 1.2 で変更: autodata と autoattribute に annotation オプションがあります。

バージョン 2.0 で変更: autodecorator が追加されました。

バージョン 2.1 で変更: autoproperty が追加されました。

バージョン 3.4 で変更: autodata と autoattribute に no-value オプションが追加されました。

注記

デコレートされた関数やメソッドをドキュメント化する場合は、autodoc はモジュールをインポートし、指定された関数またはメソッドの __doc__ 属性を検査することで docstring を取得することを覚えておいてください。これは、デコレーターがデコレートされた関数を別の関数に置き換える場合、元の __doc__ を新しい関数にコピーする必要があることを意味します。

構成

設定できる構成値もあります

autoclass_content

この値は、autoclass ディレクティブのメインボディに挿入されるコンテンツを選択します。可能な値は次のとおりです。

"class"

クラスの docstring のみが挿入されます。これがデフォルトです。automethod または autoclass の members オプションを使用して、__init__ を個別のメソッドとしてドキュメント化することもできます。

"both"

クラスと __init__ メソッドの docstring の両方が連結されて挿入されます。

"init"

__init__ メソッドの docstring のみが挿入されます。

バージョン 0.3 で追加。

クラスに __init__ メソッドがない場合、または __init__ メソッドの docstring が空の場合、ただしクラスに __new__ メソッドの docstring がある場合は、代わりにそれが使用されます。

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

autodoc_class_signature

この値は、autoclass ディレクティブで定義されたクラスの署名を表示する方法を選択します。可能な値は次のとおりです。

"mixed"

クラス名を含む署名を表示します。

"separated"

署名をメソッドとして表示します。

デフォルトは "mixed" です。

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

autodoc_member_order

この値は、自動的にドキュメント化されたメンバーをアルファベット順 (値 'alphabetical')、メンバータイプ別 (値 'groupwise')、またはソース順 (値 'bysource') でソートするかどうかを選択します。デフォルトはアルファベット順です。

ソース順の場合、モジュールはソースコードが利用可能な Python モジュールである必要があります。

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

バージョン 1.0 で変更: 'bysource' のサポート。

autodoc_default_flags

この値は、すべての autodoc ディレクティブに自動的に適用される autodoc ディレクティブフラグのリストです。サポートされているフラグは、'members'、'undoc-members'、'private-members'、'special-members'、'inherited-members'、'show-inheritance'、'ignore-module-all'、および'exclude-members'です。

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

バージョン 1.8 で廃止: autodoc_default_optionsに統合されました。

autodoc_default_options

autodoc ディレクティブのデフォルトオプション。これらはすべての autodoc ディレクティブに自動的に適用されます。オプション名を値にマッピングする辞書でなければなりません。例：

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

値を None または True に設定することは、ディレクティブにオプション名のみを与えることと同じです。

サポートされているオプションは、'members'、'member-order'、'undoc-members'、'private-members'、'special-members'、'inherited-members'、'show-inheritance'、'ignore-module-all'、'imported-members'、'exclude-members'、'class-doc-from'、および'no-value'です。

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

バージョン 2.0 で変更: 値をTrueとして受け入れるようになりました。

バージョン 2.1 で変更: 'imported-members'が追加されました。

バージョン 4.1 で変更: 'class-doc-from'が追加されました。

バージョン 4.5 で変更: 'no-value'が追加されました。

autodoc_docstring_signature

C モジュールからインポートされた関数はイントロスペクトできないため、そのような関数のシグネチャを自動的に決定することはできません。ただし、関数のドキュメンテーション文字列の最初の行にシグネチャを記述するのがよく使われる慣例です。

このブール値が True (デフォルト) に設定されている場合、autodoc は関数とメソッドのドキュメンテーション文字列の最初の行を調べ、それがシグネチャのように見える場合は、その行をシグネチャとして使用し、ドキュメンテーション文字列の内容から削除します。

autodoc は、シグネチャのように見えない最初の行で停止して、複数のシグネチャ行を探し続けます。これは、オーバーロードされた関数シグネチャを宣言する場合に便利です。

バージョン 1.1 で追加。

バージョン 3.1 で変更: オーバーロードされたシグネチャをサポート

バージョン 4.0 で変更: オーバーロードされたシグネチャは、バックスラッシュで区切る必要がなくなりました

autodoc_mock_imports

この値には、モックアップするモジュールのリストが含まれています。これは、ビルド時にいくつかの外部依存関係が満たされず、ビルドプロセスが中断する場合に役立ちます。依存関係自体のルートパッケージのみを指定し、サブモジュールは省略できます。

autodoc_mock_imports = ["django"]

django パッケージ下のすべてのインポートをモックします。

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

バージョン 1.6 で変更: この設定値では、モックする必要があるトップレベルのモジュールを宣言するだけでよくなりました。

autodoc_typehints

この値は、型ヒントをどのように表現するかを制御します。この設定は次の値を取ります

  • 'signature' – シグネチャに型ヒントを表示します（デフォルト）

  • 'description' – 関数またはメソッドの内容として型ヒントを表示します。オーバーロードされた関数またはメソッドの型ヒントは、引き続きシグネチャで表現されます。

  • 'none' – 型ヒントを表示しません

  • 'both' – シグネチャと関数またはメソッドの内容の両方に型ヒントを表示します

オーバーロードされた関数またはメソッドは、可能なすべてのオーバーロードをパラメーターのリストとして正確に表現することが不可能なため、説明に型ヒントが含まれません。

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

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

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

autodoc_typehints_description_target

この値は、autodoc_typehintsがdescriptionに設定されている場合に、ドキュメント化されていないパラメーターと戻り値の型をドキュメント化するかどうかを制御します。

デフォルト値は"all"です。これは、ドキュメント化されているかどうかにかかわらず、すべてのパラメーターと戻り値に対して型がドキュメント化されることを意味します。

"documented"に設定すると、型はドキュメンテーション文字列で既にドキュメント化されているパラメーターまたは戻り値に対してのみドキュメント化されます。

"documented_params"では、パラメーター型は、パラメーターがドキュメンテーション文字列でドキュメント化されている場合にのみ注釈が付けられます。戻り値の型は、常に注釈が付けられます (それが None の場合を除く)。

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

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

autodoc_type_aliases

型名を完全修飾オブジェクト名にマッピングする、ユーザー定義の型エイリアスの辞書。ドキュメントで評価されない型エイリアスを保持するために使用されます。デフォルトは空({})です。

型エイリアスは、プログラムが 注釈の延期評価 (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が設定されていない場合、autodocはこのコードから次のような内部マークアップを生成します

.. 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_typehints_format

この値は、型ヒントの形式を制御します。この設定は次の値を取ります

  • 'fully-qualified' – 型ヒントのモジュール名とその名前を表示します

  • 'short' – 型ヒントの先頭のモジュール名を抑制します (例: io.StringIO -> StringIO) (デフォルト)

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

バージョン 5.0 で変更: デフォルト設定が'short'に変更されました

autodoc_preserve_defaults

True の場合、関数のデフォルト引数値は、ドキュメントの生成時に評価されません。ソースコード内の値がそのまま保持されます。

バージョン 4.0 で追加: 実験的な機能として追加されました。これは将来、autodoc コアに統合されます。

autodoc_warningiserror

この値は、モジュールのインポート中にsphinx-build --fail-on-warningの動作を制御します。Falseが指定されている場合、autodocは、インポートされたモジュールが警告を発した場合に強制的にエラーを抑制します。デフォルトでは、Trueです。

バージョン 8.1 で変更: このオプションは、--fail-on-warningが早期に終了しなくなったため、効果がなくなりました。

autodoc_inherit_docstrings

この値は、ドキュメンテーション文字列の継承を制御します。True に設定すると、クラスまたはメソッドのドキュメンテーション文字列は、明示的に設定されていない場合、親から継承されます。

デフォルトはTrueです。

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

suppress_warnings

autodocは、suppress_warningsを使用して警告メッセージを抑制することをサポートしています。さらに、次の警告タイプを許可します

  • autodoc

  • autodoc.import_object

ドキュメンテーション文字列の前処理

autodoc は、次の追加のイベントを提供します

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

バージョン 0.4 で追加。

autodoc がドキュメンテーション文字列を読み取り、処理したときに発生します。lines は、処理されたドキュメンテーション文字列の行である文字列のリストであり、イベントハンドラーは、Sphinx が出力に含める内容を変更するためにインプレースで変更できます。

パラメーター:

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

  • what – ドキュメント文字列が属するオブジェクトの型（"module", "class", "exception", "function", "method", "attribute" のいずれか）

  • name – オブジェクトの完全修飾名

  • obj – オブジェクト自体

  • options – ディレクティブに与えられたオプション：inherited_members, undoc_members, show_inheritance, no-index の属性を持つオブジェクト。これらの属性は、autoディレクティブに同じ名前のフラグオプションが与えられた場合にtrueとなる

  • 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 で追加されました。

autodocがオブジェクトのシグネチャをフォーマットしたときに発生します。イベントハンドラは、Sphinxが出力に記述する内容を変更するために、新しいタプル(signature, return_annotation)を返すことができます。

パラメーター:

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

  • what – ドキュメント文字列が属するオブジェクトの型（"module", "class", "exception", "function", "method", "attribute" のいずれか）

  • name – オブジェクトの完全修飾名

  • obj – オブジェクト自体

  • options – ディレクティブに与えられたオプション：inherited_members, undoc_members, show_inheritance, no-index の属性を持つオブジェクト。これらの属性は、autoディレクティブに同じ名前のフラグオプションが与えられた場合にtrueとなる

  • signature – 関数のシグネチャ。 "(parameter_1, parameter_2)" の形式の文字列、またはイントロスペクションに失敗し、ディレクティブでシグネチャが指定されていない場合は None。

  • return_annotation – 関数の戻り値のアノテーション。 " -> annotation" の形式の文字列。戻り値のアノテーションがない場合は None。

sphinx.ext.autodoc モジュールは、イベントautodoc-process-docstringで一般的に必要なドキュメント文字列処理のためのファクトリ関数を提供します。

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

すべてのドキュメント文字列の最初の pre 行と最後の post 行を削除するリスナーを返します。what が文字列のシーケンスである場合、what 内の型のドキュメント文字列のみが処理されます。

次のように使用します（例えば、conf.py の setup() 関数内）。

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: Sequence[str] | None = None, keepempty: bool = False, exclude: bool = False) → Callable[ソース]

marker 正規表現に一致する行の間の行を保持するか、exclude がTrueの場合は除外するリスナーを返します。一致する行がない場合、結果のドキュメント文字列は空になるため、keepempty がtrueでない限り、変更は行われません。

what が文字列のシーケンスである場合、what 内の型のドキュメント文字列のみが処理されます。

autodoc-process-bases(app, name, obj, options, bases)

autodocがクラスを読み込み、処理して基底クラスを決定したときに発生します。bases は、イベントハンドラが**インプレース**で変更して、Sphinxが出力に記述する内容を変更できるクラスのリストです。 show-inheritance オプションが指定されている場合にのみ発生します。

パラメーター:

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

  • name – オブジェクトの完全修飾名

  • obj – オブジェクト自体

  • options – クラスディレクティブに与えられたオプション

  • bases – 基底クラスのシグネチャのリスト。上記を参照。

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

バージョン 4.3 で変更: bases は、基底クラス名として文字列を含めることができます。これは reStructuredText として処理されます。

メンバーのスキップ

autodocでは、次のイベントを使用することにより、メンバーをドキュメントに含めるかどうかを決定するためのカスタムメソッドを定義できます。

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

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

autodocが、メンバーをドキュメントに含めるかどうかを決定する必要があるときに発生します。ハンドラが True を返すと、メンバーは除外されます。ハンドラが False を返すと、メンバーは含まれます。

複数の有効な拡張機能が autodoc-skip-member イベントを処理する場合、autodocはハンドラによって返された最初の非 None 値を使用します。ハンドラは、autodocと他の有効な拡張機能のスキップ動作に戻るために None を返す必要があります。

パラメーター:

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

  • what – ドキュメント文字列が属するオブジェクトの型（"module", "class", "exception", "function", "method", "attribute" のいずれか）

  • name – オブジェクトの完全修飾名

  • obj – オブジェクト自体

  • skip – ユーザーハンドラが決定をオーバーライドしない場合、autodocがこのメンバーをスキップするかどうかを示すブール値

  • options – ディレクティブに与えられたオプション：inherited_members, undoc_members, show_inheritance, no-index の属性を持つオブジェクト。これらの属性は、autoディレクティブに同じ名前のフラグオプションが与えられた場合にtrueとなる