sphinx.ext.autodoc -- docstringからのドキュメントの取り込み

この拡張機能は、docstringでドキュメントが書かれているモジュールをインポートして、そのdocstringから、半自動的にドキュメントを取り込みます。

注釈

Sphinx(実際にはSphinxを実行しているPythonインタプリタ)がモジュールを見つけるためには、そのモジュールはインポート可能になっていなければなりません。これは、インポートしたいモジュールやパッケージがsys.pathで設定されているディレクトリのどれかに入っている必要があるということです。設定ファイル内で、適宜sys.pathを調整してください。

警告

autodoc はドキュメンテーションされるモジュールを インポート します. もしインポートによる副作用があれば、 sphinx-build が実行されるとき autodoc により実行されます。

もしあなたが (ライブラリモジュールではなく) スクリプトをドキュメント化したいのであれば、スクリプトのメインルーチンが if __name__ == '__main__' 条件により保護されていることを確認して下さい。

この機能をうまく働かせるためには、docstringは正しいreStructuredTextのフォーマットに従って記述されている必要があります。また、すべてのSphinxのマークアップをdocstringの中に書くことができ、最終的に正しくドキュメンテーションされます。手書きのドキュメントと一緒にモジュールのドキュメントを作成する場合には、純粋なAPIのドキュメントを同時に自動生成できるため、この機能を使うことで両方を同時に管理する苦痛が軽減されます。

If you prefer NumPy or Google style docstrings over reStructuredText, you can also enable the napoleon extension. napoleon is a preprocessor that converts your docstrings to correct reStructuredText before autodoc processes them.

ディレクティブ

autodoc は通常のpy:module, py:classなどのディレクティブに似た別バージョンのディレクティブを提供します。ドキュメントのパース時に指定されたモジュールを読み込んで、docstringを抽出して、その内容を通常のpy:module, py:classディレクティブと一緒に差込みます。

注釈

py:classを宣言したときに、既に定義されているpy:moduleの中に配置されるのと同様に、autoclassも同じように振舞います。automethodpy:classについても同様です。

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

モジュール、クラス、例外のドキュメントを作成します。これらのディレクティブは、デフォルトでは指定されたオブジェクトのdocstringだけを読み込みます:

.. autoclass:: Noodle

これを実行すると以下のようなreSTのソースコードが生成されます:

.. class:: Noodle

   Noodle's docstring.

"auto"ディレクティブは、取り込むだけでなく、自分自身のコンテンツを書くことができます。自動取り込みされたドキュメントの後に挿入されます。

そのため、以下のサンプルのように、自動のドキュメントと、手動で書いたメンバーのドキュメントを混ぜてかくこともできます:

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

   .. method:: boil(time=10)

      Boil the noodle *time* minutes.

オプション/進んだ使い方

  • 自動的にメンバーの関数やプロパティのドキュメントも取り込みたい場合には、membersオプションを使用します:

    .. automodule:: noodle
       :members:
    

    このように書くと、すべてのモジュールのメンバーを(再帰的に)ドキュメントにしていきます。そして:

    .. autoclass:: Noodle
       :members:
    

    これをビルドすると、すべての非プライベートの関数とプロパティ(名前が_以外から始まる)のドキュメントが取り込まれます。

    For modules, __all__ will be respected when looking for members unless you give the ignore-module-all flag option. Without ignore-module-all, the order of the members will also be the order in __all__.

    また、ドキュメントとして出力したいメンバーのリストを明示的に書くと、指定したメンバーのドキュメントのみが生成されます:

    .. autoclass:: Noodle
       :members: eat, slurp
    
  • If you want to make the members option (or other options described below) the default, see autodoc_default_options.

    ちなみに

    You can use a negated form, 'no-flag', as an option of autodoc directive, to disable it temporarily. For example:

    .. automodule:: foo
       :no-undoc-members:
    
  • undoc-membersフラグオプションを指定しないと、docstringの付いていないメンバーは省略されます:

    .. automodule:: noodle
       :members:
       :undoc-members:
    
  • "プライベート"メンバー (_private__private といった名前を持つ)は、 private-members フラグをセットすると含まれるようになります。

    バージョン 1.1 で追加.

  • Pythonの"特殊メンバー" (__special__ のような名前)は、 special-members フラグをセットすると、含まれるようになります:

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

    このようにセットすると、クラスのプライベートメンバー、特殊メンバーの両方が出力されるようになります。

    バージョン 1.1 で追加.

    バージョン 1.2 で変更: オプションは引数を持てるようになりました。例えば、 __ で始まるメンバーをドキュメントしたい場合などに指定します。

  • クラスと例外で、membersと一緒にinherited-membersフラグオプションが指定されていない場合には、たとえ全てのメンバーにドキュメントが書かれていたとしても、ベースクラスで定義されているメンバーは省略されます:

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

    このフラグとundoc-membersを同時に適用すると、クラスとモジュールの持っている、すべての利用可能なメンバーのドキュメントが作成されるようになります。

    注意: もしもdocstringがreST形式でないモジュールで定義されたメンバーがあると、マークアップエラーになるでしょう。

    バージョン 0.3 で追加.

  • 通常は内省機能を使って情報を取得しますが、明示的にドキュメントを書くことで、通常の文法で定義された呼び出し可能なオブジェクト(関数、メソッド、クラス)の呼び出し規約(変数名など)を上書きすることができます:

    .. autoclass:: Noodle(type)
    
       .. automethod:: eat(persona)
    

    この機能はデコレータなどによって、メソッドの呼び出し規約が内省機能で取れない状態になっている場合に便利です。

    バージョン 0.4 で追加.

  • automoduleと、autoclassautoexceptionディレクティブはshow-inheritanceというオプションをサポートしています。これが設定されると、クラスのシグニチャの直前に、継承しているベースクラスのリストが表示されるようになります。automoduleに対して使用すると、モジュール内でドキュメントが記述されているすべてのクラスのベースクラスが表示されるようになります。

    バージョン 0.4 で追加.

  • autodocのすべてのディレクティブはnoindexというフラグオプションをサポートしています。これは標準のpy:functionなどと同様の効果があります。ドキュメントが生成されるオブジェクトと、それに含まれるメンバーに対する索引が生成されなくなります。

    バージョン 0.4 で追加.

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

    バージョン 0.5 で追加.

  • automoduleautoclassmember-orderというオプションを持っています。これを設定すると、このディレクティブの中でのみグローバルなautodoc_member_orderという設定をオーバーライドできます。

    バージョン 0.6 で追加.

  • メンバーのドキュメント生成をサポートしているディレクティブはexclude-membersというオプションも持っています。これはすべてのドキュメントを生成する場合に、除外したいメンバーの名前をひとつだけ追加するのに使用します。

    バージョン 0.6 で追加.

  • membersオプションが設定されているautomoduleディレクティブの中では、__module__属性がautomoduleで与えられたモジュール名と等しいメンバーのみのドキュメントが生成されます。これはインポートされたクラスや関数のドキュメントまで生成しないための措置です。 imported-members オプションによって、この動作をさせないよう指定でき、全てのメンバーをドキュメント化します。インポートしたモジュールの属性はドキュメント化されないことに注意してください。これは、属性のドキュメント化は現在のモジュールのソースコードをパースして行うためです。

    バージョン 1.2 で追加.

  • ビルド時に依存モジュールがインポートできない場合に、 ビルド処理を終了するインポートエラーを防止する為に autodoc_mock_imports 内のモジュールリストを追加します。

    バージョン 1.3 で追加.

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

これらのディレクティブはautoclassなどと同じように動作しますが、メンバー内のドキュメント生成のオプションはありません。

autodata and autoattribute support the annotation option. The option controls how the value of variable is shown. If specified without arguments, only the name of the variable will be printed, and its value is not shown:

.. autodata:: CD_DRIVE
   :annotation:

If the option specified with arguments, it is printed after the name as a value of the variable:

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

By default, without annotation option, Sphinx tries to obtain the value of the variable and print it after the name.

モジュールのデータメンバーとクラス属性については、特別なフォーマットでコメントの中に (コメントの開始に単に # を使う代わりに #: を使用して)、または定義の 後の docstring の中にドキュメンテーションを入れることができます。コメントは、定義の 前の それ自身の行、または代入の直後の 同じ行に 置く必要があります。後者の形式は1行のみに制限されます。

これが意味するのは、次のクラス定義ですべての属性が autodocument 化できるということです:

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 で変更: autodataautoattribute がdocstringにも対応しました。

バージョン 1.1 で変更: 代入文の直後にコメントドキュメントを書けるようになりました。

バージョン 1.2 で変更: autodataautoattributeannotation オプションがあります。

バージョン 2.0 で変更: autodecorator added.

注釈

もしもデコレータのついた関数やメソッドのドキュメントを生成する場合には、autodocが、実際にモジュールをインポートして、指定された関数やメソッドの__doc__属性を見てドキュメントを生成しているということに注意してください。これは、もしデコレートされた関数が他のものに置き換えられる場合には、元の__doc__の内容を新しい関数にもコピーしなければ動作しないということを意味しています。

Python 2.5以降であれば、functools.wraps()を使用することで、このあたりまできちんと面倒を見てくれます。

設定

There are also config values that you can set:

autoclass_content

この値を指定することで、本体のautoclassディレクティブにどの内容を追加するのかを選択できます。指定可能な値は以下の通りです:

"class"

クラスのdocstringだけが挿入されます。これがデフォルトの動作になります。automethodを使用するか、autoclassに対してmembersオプションを設定することで、__init__の内容は別のメソッドとしてドキュメント化できます。

"both"

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

"init"

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

バージョン 0.3 で追加.

クラス内に __init__ メソッドが定義されていない、または __init__ メソッドのドックストリングが空で __new__ メソッドにドックストリングが記述されている場合は、 __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 で非推奨: Integrated into autodoc_default_options.

autodoc_default_options

The default options for autodoc directives. They are applied to all autodoc directives automatically. It must be a dictionary which maps option names to the values. For example:

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

Setting None or True to the value is equivalent to giving only the option name to the directives.

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 で変更: Accepts True as a value.

バージョン 2.1 で変更: Added 'imported-members'.

autodoc_docstring_signature

Cモジュールからインポートされた関数は、情報を取得できないため、これらの関数に関するシグニチャを自動的に決定することはできません。しかし、これを使用すると、これらの関数のdocstringの最初の行に、これらの関数のシグニチャを入れられます。

もしこの設定を True (デフォルト)にすると、autodocは関数やメソッドのdocstringの最初の行を見て、もしシグニチャのような情報が書かれていたら、その行をシグニチャとして読み込み、docstringからはその行の内容を削除して扱います。

バージョン 1.1 で追加.

autodoc_mock_imports

This value contains a list of modules to be mocked up. This is useful when some external dependencies are not met at build time and break the building process. You may only specify the root package of the dependencies themselves and omit the sub-modules:

autodoc_mock_imports = ["django"]

Will mock all imports under the django package.

バージョン 1.3 で追加.

バージョン 1.6 で変更: This config value only requires to declare the top-level modules that should be mocked.

autodoc_typehints

This value controls how to represents typehints. The setting takes the following values:

  • 'signature' -- Show typehints as its signature (default)

  • 'none' -- Do not show typehints

autodoc_warningiserror

This value controls the behavior of sphinx-build -W during importing modules. If False is given, autodoc forcedly suppresses the error if the imported module emits warnings. By default, True.

autodoc_inherit_docstrings

This value controls the docstrings inheritance. If set to True the docstring for classes or methods, if not explicitly set, is inherited form parents.

デフォルト値は True です。

バージョン 1.7 で追加.

suppress_warnings

autodoc supports to suppress warning messages via suppress_warnings. It allows following warnings types in addition:

  • autodoc

  • autodoc.import_object

Docstringのプリプロセス

autodocは以下のイベントを追加で提供します:

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

バージョン 0.4 で追加.

autodocがdocstringを読み込んで処理をするタイミングで呼び出されます。linesは処理されたdocstringが入っている、文字列のリストです。このリストはイベントハンドラの中で変更でき、この結果を利用します。

パラメータ
  • app -- Sphinxのアプリケーションオブジェクト

  • what -- docstringが属するオブジェクトの型 (以下のうちのどれか "module", "class", "exception", "function", "method", "attribute")

  • name -- オブジェクトの完全な修飾付きの名前

  • obj -- オブジェクト自身

  • options -- ディレクティブに与えられたオプションです。 inherited_members, undoc_members, show_inheritance, noindex などの属性をもったオブジェクトです。同じ名前のフラグオプションが渡されるとtrueになります。

  • lines -- docstringの行数。上記を参照。

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

バージョン 0.5 で追加.

autodocがオブジェクトのシグニチャをフォーマットしているときに呼び出されます。イベントハンドラは新しいタプル(signature, return_annotation)を返すことができ、Sphinxはこの出力を使ってドキュメントを生成します。

パラメータ
  • app -- Sphinxのアプリケーションオブジェクト

  • what -- docstringが属するオブジェクトの型 (以下のうちのどれか "module", "class", "exception", "function", "method", "attribute")

  • name -- オブジェクトの完全な修飾付きの名前

  • obj -- オブジェクト自身

  • options -- ディレクティブに与えられたオプションです。 inherited_members, undoc_members, show_inheritance, noindex などの属性をもったオブジェクトです。同じ名前のフラグオプションが渡されるとtrueになります。

  • signature -- "(parameter_1, parameter_2)" という形式の文字列で示される関数シグニチャか、あるいは、イントロスペクションが成功せず、シグニチャをディレクティブ中で特定できない場合には None となります。

  • return_annotation -- アノテーションを " -> annotation" という形式の文字列で返す関数か、アノテーションを返さない場合は None となります。

sphinx.ext.autodocモジュールではautodoc-process-docstringイベント内でdocstringを処理する上で一般的に必要とされるようなファクトリー関数をいくつか提供しています:

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

全てのdocstringの最初の pre 行と、最後の post 行を削除するリスナーを返します。 what として文字列の配列が渡されると、この what に含まれているタイプのdocstringだけが処理されます。

この関数は 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, keepempty: bool = False, exclude: bool = False) → Callable[ソース]

marker の正規表現にマッチしている行の間だけを保持する、または exclude がtrueならば除外する、リスナーを返します。もしも一行もマッチしない場合には、docstringが空になる可能性がありますが、 keepempty がtrueでない場合には、変更されません。

もしも what として、文字列の配列が渡されると、この what に含まれているタイプのdocstringだけが処理されます。

メンバーのスキップ

autodocでは以下のイベントを発行することで、指定されたメンバーをドキュメントに含めるかどうかをユーザが決定できるようになっています:

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

バージョン 0.5 で追加.

autodocがメンバーをドキュメントに含めるかどうかを決定するときに呼ばれます。もしもこのハンドラーがTrueを返すとメンバーのドキュメントは外されます。Falseを返すと含まれるようになります。

If more than one enabled extension handles the autodoc-skip-member event, autodoc will use the first non-None value returned by a handler. Handlers should return None to fall back to the skipping behavior of autodoc and other enabled extensions.

パラメータ
  • app -- Sphinxのアプリケーションオブジェクト

  • what -- docstringが属するオブジェクトの型 (以下のうちのどれか "module", "class", "exception", "function", "method", "attribute")

  • name -- オブジェクトの完全な修飾付きの名前

  • obj -- オブジェクト自身

  • skip -- ユーザーハンドラーが上書きしない場合に、autodocがこのメンバーを飛ばすかどうかの真偽値。

  • options -- ディレクティブに与えられたオプションです。 inherited_members, undoc_members, show_inheritance, noindex などの属性をもったオブジェクトです。同じ名前のフラグオプションが渡されるとtrueになります。