この拡張機能は、docstringでドキュメントが書かれているモジュールをインポートして、そのdocstringから、半自動的にドキュメントを取り込みます。
Note
Sphinx(実際にはSphinxを実行しているPythonインタプリタ)がモジュールを見つけられるためには、そのモジュールはインポート可能になっていなければなりません。これは、インポートしたいモジュールやパッケージがsys.pathで設定されているディレクトリのどれかに入っている必要があるということです。設定ファイル内で、適宜sys.pathを調整してください。
この機能がうまく働くためには、docstringは正しいreStructuredTextのフォーマットに従って記述されている必要があります。また、すべてのSphinxのマークアップをdocstringの中に書くことができ、最終的に正しくドキュメンテーションされます。手書きのドキュメントと一緒にモジュールのドキュメントを作成する場合には、純粋なAPIのドキュメントを同時に自動生成できるため、この機能を使うと両方を同時に管理しなければならないという痛みを和らげることができます。
autodoc`は通常の:rst:dir:`module, classなどのディレクティブに似た別バージョンのディレクティブを提供します。ドキュメントのパース時に指定されたモジュールを読み込んで、docstringを抽出して、その内容を通常のmodule, classディレクティブと一緒に差込みます。
Note
classを宣言したときに、既に定義されているmoduleの中に配置されるのと同様に、autoclassも同じように振舞います。method とclassについても同様です。
モジュール、クラス、例外のドキュメントを作成します。これらのディレクティブは、デフォルトでは指定されたオブジェクトのdocstringだけを読み込みます:
.. autoclass:: Noodle
これを実行すると以下のようなreSTのソースコードが生成されます:
.. class:: Noodle
Noodleのdocstring.
“auto”ディレクティブは、取り込むだけでなく、自分自身のコンテンツを書くことができます。自動取り込みされたドキュメントの後に挿入されます。
そのため、以下のサンプルのように、自動のドキュメントと、手動で書いたメンバーのドキュメントを混ぜてかくこともできます:
.. autoclass:: Noodle
:members: eat, slurp
.. method:: boil(time=10)
*time* 分だけ、麺をゆでます。
オプション/進んだ使い方
もしも自動的にメンバーの関数やプロパティのドキュメントも取り込みたい場合には、membersオプションを使用します:
.. automodule:: noodle
:members:
このように書くと、すべてのモジュールのメンバーを再帰的にドキュメントにしていきます。そして:
.. autoclass:: Noodle
:members:
これをビルドすると、すべての非プライベートの関数とプロパティ(名前が_以外から始まる)のドキュメントが取り込まれます。
また、ドキュメントを出力したいメンバーのリストを明示的に書くと、それらの指定されたメンバーのドキュメントが生成されます:
.. autoclass:: Noodle
:members: eat, slurp
undoc-membersフラグオプションを指定しないと、docstringの付いていないメンバーは省略されます:
.. automodule:: noodle
:members:
:undoc-members:
クラスと例外で、membersと一緒にinherited-membersフラグオプションが指定されていない場合には、ベースクラスで定義されているメンバーは省略されます。を指定しないと、docstringの付いていないメンバーは省略されます:
.. autoclass:: Noodle
:members:
:inherited-members:
このフラグとundoc-membersを同時に適用すると、クラスとモジュールの持っている、すべての利用可能なメンバーのドキュメントが作成されるようになります。
注意: もしもdocstringがreST形式でないモジュールで定義されたメンバーがあると、マークアップエラーになるでしょう。
New in version 0.3.
通常は内省機能を使って情報を取得しますが、明示的にドキュメントを書くことで、通常の文法で定義された呼び出し可能なオブジェクト(関数、メソッド、クラス)の呼び出し規約(変数名など)を上書きすることができます:
.. autoclass:: Noodle(type)
.. automethod:: eat(persona)
この機能はデコレータなどによって、メソッドの呼び出し規約が内省機能で取れない状態になっている場合に便利です。
New in version 0.4.
autodocのすべてのディレクティブはnoindexというフラグオプションをサポートしています。これは標準のfunctionなどと同様の効果があります。ドキュメントが生成されるオブジェクトと、それに含まれるメンバーに対する索引が生成されなくなります。
New in version 0.4.
automoduleは標準のmoduleディレクティブがサポートしているsynopsis, platform, deprecatedオプションをサポートしています。
New in version 0.5.
automoduleとautoclassはmember-orderというオプションを持っています。これを設定すると、このディレクティブの中でのみグローバルなautodoc_member_orderという設定をオーバーライドすることができます。
New in version 0.6.
メンバーのドキュメント生成をサポートしているディレクティブはexclude-membersというオプションも持っています。これはすべてのドキュメントを生成する場合に、除外したいメンバーの名前をひとつだけ追加するのに使用します。
New in version 0.6.
Note
membersオプションが設定されているautomoduleディレクティブの中では、__module__属性がautomoduleで与えられたモジュール名と等しいメンバーのみのドキュメントが生成されます。これはインポートされたクラスや関数のドキュメントまで生成しないための措置です。
これらのディレクティブはautoclassなどと同じように動作しますが、メンバー内のドキュメント生成のオプションはありません。
モジュールのデータメンバーとクラスの属性は、属性定義の前の行の特別な書式のコメント、もしくは、定義の後のdocstringのドキュメントのどちらかを参照してドキュメントを生成します。そのため、以下のサンプルではどちらの属性もドキュメントが生成されます:
class Foo:
"""Fooクラスに関するdocstring"""
#: Foo.bar属性に関するdocコメント
bar = 1
baz = 2
"""Foo.baz属性に関するdocstring"""
Changed in version 0.6: autodataとautoattribute がdocstringにも対応しました。
Note
もしもデコレータのついた関数やメソッドのドキュメントを生成する場合には、autodocが、実際にモジュールをインポートして、指定された関数やメソッドの__doc__属性を見てドキュメントを生成しているということに注意してください。これは、もしデコレートされた関数が他のものに置き換えられる場合には、元の__doc__の内容を新しい関数にもコピーしなければ動作しないということを意味しています。
Python 2.5以降であれば、functools.wraps()を使用することで、このあたりまできちんと面倒を見てくれます。
autodoc拡張には、新しい設定値がいくつかあります。
この値を指定することで、本体のautoclassディレクティブにどの内容を追加するのかを選択することができます。指定可能な値は以下の通りです:
New in version 0.3.
これの設定を変更することで、ドキュメントのついたメンバーをアルファベット順にソートするか('alphabetical')、もしくはメンバーのタイプによって('groupwise')ソートするか、ソースコードの定義順('bysource')にソートするかを変更することができます。デフォルトはアルファベット順です。
ソースコードの定義順を指定する場合には、対象のモジュールはPythonモジュールで、ソースコードが利用できるようになっていなければなりません。
New in version 0.6.
Changed in version 1.0: 'bysource' がサポートされました。
この値には、すべてのautodocディレクティブに対して、自動で適用したいフラグのリストを設定します。設定できるフラグは、 'members', 'undoc-members', 'inherited-members', 'show-inheritance' です。
これらのフラグの一つをこの設定値に設定した場合、否定形の 'no-flag' をautodocディレクティブの中で指定することで、個別に機能をオフにすることができます。例えば、 autodoc_default_flags に ['members', 'undoc-members'] と指定した場合:
.. automodule:: foo
:no-undoc-members:
このように記述すると、 :members: だけが指定されているという解釈がされます。
New in version 1.0.
autodocは以下のイベントを追加で提供します:
New in version 0.4.
autodocがdocstringを読み込んで処理をするタイミングで呼び出されます。linesは処理されたdocstringが入っている、文字列のリストです。このリストはイベントハンドラの中で変更することができ、この結果を利用します。
| Param app: | Sphinxのアプリケーションオブジェクトです |
|---|---|
| Param what: | docstringが所属しているオブジェクトのタイプです。"module", "class", "exception", "function", "method", "attribute"のどれかになります。 |
| Param name: | 装飾名が完全についているオブジェクトの名前です |
| Param obj: | オブジェクトそのものです |
| Param options: | ディレクティブに与えられたオプションです。inherited_members, undoc_members, show_inheritance, noindexなどの属性をもったオブジェクトです。同じ名前のフラグオプションが渡されるとtrueになります。 |
| Param lines: | docstringの行の配列です。上記の説明を参照。 |
New in version 0.5.
autodocがオブジェクトのシグニチャをフォーマットしているときに呼び出されます。イベントハンドラは新しいタプル(signature, return_annotation)を返すことができ、Sphinxはこの出力を使ってドキュメントを生成します。
| Param app: | Sphinxのアプリケーションオブジェクトです |
|---|---|
| Param what: | docstringが所属しているオブジェクトのタイプです。"module", "class", "exception", "function", "method", "attribute"のどれかになります。 |
| Param name: | 装飾名が完全についているオブジェクトの名前です |
| Param obj: | オブジェクトそのものです |
| Param options: | ディレクティブに与えられたオプションです。inherited_members, undoc_members, show_inheritance, noindexなどの属性をもったオブジェクトです。同じ名前のフラグオプションが渡されるとtrueになります。 |
| Param signature: | |
| function signature, as a string of the form "(parameter_1, parameter_2)"という文字列の形式の関数のシグニチャです。あるいは、内部情報の取得に失敗して、なおかつディレクティブで指定されなかった場合にはNoneとなります。 | |
| Param return_annotation: | |
| 返り値が指定されると、" -> annotation"という形式の文字列になります。もしも指定されていない場合にはNoneとなります。 | |
sphinx.ext.autodocモジュールではautodoc-process-docstringイベント内でdocstringを処理する上で一般的に必要とされるようなファクトリー関数をいくつか提供しています:
全ての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']))
marker の正規表現にマッチしている行の間だけを保持するリスナーを返します。もしも一行もマッチしない場合には、docstringが空になる可能性がありますが、 keepempty がtrueでない場合には、変更されません。
もしも what として、文字列の配列が渡されると、この what に含まれているタイプのdocstringだけが処理されます。
autodocでは以下のイベントを発行することで、指定されたメンバーをドキュメントに含めるかどうかをユーザが決定できるようになっています:
New in version 0.5.
autodocがメンバーをドキュメントに含めるかどうかを決定するときに呼ばれます。もしもこのハンドラーがTrueを返すとメンバーのドキュメントは外されます。Falseを返すと含まれるようになります。
| Param app: | Sphinxのアプリケーションオブジェクトです |
|---|---|
| Param what: | docstringが所属しているオブジェクトのタイプです。"module", "class", "exception", "function", "method", "attribute"のどれかになります。 |
| Param name: | 装飾名が完全についているオブジェクトの名前です |
| Param obj: | オブジェクトそのものです |
| Param skip: | もしもユーザが作為を入れようとしなかった場合に、Sphinxがスキップをするかどうかについて決断した結果です |
| Param options: | ディレクティブに与えられたオプションです。inherited_members, undoc_members, show_inheritance, noindexなどの属性をもったオブジェクトです。同じ名前のフラグオプションが渡されるとtrueになります。 |