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:
    

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

    モジュールに関しては、もしあればメンバーを探すのに __all__ が利用されます。出力されるメンバーの順序も、 __all__ の順序になります。

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

    .. autoclass:: Noodle
       :members: eat, slurp
    
  • もしも、デフォルトで members オプション(や、これから説明する他のオプション)を有効にしたい場合には、 autodoc_default_flags を参照してください。

  • 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フラグオプションが指定されていない場合には、例えすべてのメンバーにドキュメントが書かれていたとしても、ベースクラスで定義されているメンバーは省略されます。を指定しないと、docstringの付いていないメンバーは省略されます:

    .. 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::
.. autodata::
.. automethod::
.. autoattribute::

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

autodataautoattributeannotation オプションをサポートします。 annotation オプションを使用しない場合、オブジェクトの表記法がドキュメントへ表示されます。 オプションへ引数を指定しない場合、オブジェクトの名前のみが表示されます:

.. autodata:: CD_DRIVE
   :annotation:

名前の後に何が表示されるべきかsphinxに与えることができます:

.. autodata:: CD_DRIVE
   :annotation: = your CD device 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 オプションがあります。

注釈

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

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

autodoc拡張には、新しい設定値がいくつかあります。

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

この値には、すべてのautodocディレクティブに対して、自動で適用したいフラグのリストを設定します。設定できるフラグは、 'members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance' です。

これらのフラグの一つをこの設定値に設定した場合、否定形の 'no-flag' をautodocディレクティブの中で指定することで、個別に機能をオフにできます。例えば、 autodoc_default_flags['members', 'undoc-members'] と指定した場合:

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

このように記述すると、 :members: だけが指定されているという解釈がされます。

バージョン 1.0 で追加.

autodoc_docstring_signature

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

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

バージョン 1.1 で追加.

autodoc_mock_imports

この値はモックアップされるモジュールのリストを含みます。これはビルド時もしくはビルド過程の中断時にいくつかの外部依存が満たされない時に有用です。

バージョン 1.3 で追加.

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, post=0, what=None)[ソース]

全ての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, what=None, keepempty=False, exclude=False)[ソース]

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になります。