.. highlight:: rest
この拡張機能は、docstringでドキュメントが書かれているモジュールをインポートして、そのdocstringから、半自動的にドキュメントを取り込みます。
ノート
Sphinx(実際にはSphinxを実行しているPythonインタプリタ)がモジュールを見つけられるためには、そのモジュールはインポート可能になっていなければなりません。これは、インポートしたいモジュールやパッケージがsys.pathで設定されているディレクトリのどれかに入っている必要があるということです。設定ファイル内で、適宜sys.pathを調整してください。
この機能がうまく働くためには、docstringは正しいreStructuredTextのフォーマットに従って記述されている必要があります。また、すべてのSphinxのマークアップをdocstringの中に書くことができ、最終的に正しくドキュメンテーションされます。手書きのドキュメントと一緒にモジュールのドキュメントを作成する場合には、純粋なAPIのドキュメントを同時に自動生成できるため、この機能を使うと両方を同時に管理しなければならないという痛みを和らげることができます。
autodoc`は通常の:dir:`module, classなどのディレクティブに似た別バージョンのディレクティブを提供します。ドキュメントのパース時に指定されたモジュールを読み込んで、docstringを抽出して、その内容を通常のmodule, classディレクティブと一緒に差込みます。
モジュール、クラス、例外のドキュメントを作成します。これらのディレクティブは、デフォルトでは指定されたオブジェクトのdocstringだけを読み込みます:
.. autoclass:: Noodleこれを実行すると以下のようなreSTのソースコードが生成されます:
.. class:: Noodle Noodleのdocstring.“auto”ディレクティブは、取り込むだけでなく、自分自身のコンテンツを書くことができます。自動取り込みされたドキュメントの後に挿入されます。
そのため、以下のサンプルのように、自動のドキュメントと、手動で書いたメンバーのドキュメントを混ぜてかくこともできます:
.. autoclass:: Noodle :members: eat, slurp .. method:: boil(time=10) *time* 分だけ、麺をゆでます。オプション/進んだ使い方
もしも自動的にメンバーの関数やプロパティのドキュメントも取り込みたい場合には、membersオプションを使用します:
.. autoclass:: Noodle :members:これをビルドすると、すべての非プライベートの関数とプロパティ(名前が_以外から始まる)のドキュメントが取り込まれます。また以下のようにすると:
.. autoclass:: Noodle :members: eat, slurp指定されたメンバーのドキュメントだけが生成されます。
undoc-membersフラグオプションを指定しないと、docstringの付いていないメンバーは省略されます:
.. autoclass:: Noodle :members: :undoc-members:クラスと例外で、membersと一緒にinherited-membersフラグオプションが指定されていない場合には、ベースクラスで定義されているメンバーは省略されます。を指定しないと、docstringの付いていないメンバーは省略されます:
.. autoclass:: Noodle :members: :inherited-members:このフラグとundoc-membersを同時に適用すると、クラスとモジュールの持っている、すべての利用可能なメンバーのドキュメントが作成されるようになります。
バージョン 0.3 で追加.
通常は内省機能を使って情報を取得しますが、明示的にドキュメントを書くことで、通常の文法で定義された呼び出し可能なオブジェクト(関数、メソッド、クラス)の呼び出し規約(変数名など)を上書きすることができます:
.. autoclass:: Noodle(type) .. automethod:: eat(persona)この機能はデコレータなどによって、メソッドの呼び出し規約が内省機能で取れない状態になっている場合に便利です。
バージョン 0.4 で追加.
automoduleと、autocalss、autoexceptionディレクティブはshow-inheritanceというオプションをサポートしています。これが設定されると、クラスのシグニチャの直前に、継承しているベースクラスのリストが表示されるようになります。automoduleに対して使用されると、モジュール内でドキュメントが記述されているすべてのクラスのベースクラスが表示されるようになります。
バージョン 0.4 で追加.
autodocのすべてのディレクティブはnoindexというフラグオプションをサポートしています。これは標準のfunctionなどと同様の効果があります。ドキュメントが生成されるオブジェクトと、それに含まれるメンバーに対する索引が生成されなくなります。
バージョン 0.4 で追加.
automoduleは標準のmoduleディレクティブがサポートしているsynopsis, platform, deprecatedオプションをサポートしています。
バージョン 0.5 で追加.
automoduleとautoclassはmember-orderというオプションを持っています。これを設定すると、このディレクティブの中でのみグローバルなautodoc_member_orderという設定をオーバーライドすることができます。
バージョン 0.6 で追加.
メンバーのドキュメント生成をサポートしているディレクティブはexclude-membersというオプションも持っています。これはすべてのドキュメントを生成する場合に、除外したいメンバーの名前をひとつだけ追加するのに使用します。
バージョン 0.6 で追加.
ノート
membersオプションが設定されているautomoduleディレクティブの中では、__module__属性がautomoduleで与えられたモジュール名と等しいメンバーのみのドキュメントが生成されます。これはインポートされたクラスや関数のドキュメントまで生成しないための措置です。
これらのディレクティブはautoclassなどと同じように動作しますが、メンバー内のドキュメント生成のオプションはありません。
モジュールのデータメンバーとクラスの属性は、属性定義の前の行の特別な書式のコメント、もしくは、定義の後のdocstringのドキュメントのどちらかを参照してドキュメントを生成します。そのため、以下のサンプルではどちらの属性もドキュメントが生成されます:
class Foo:
"""Fooクラスに関するdocstring"""
#: Foo.bar属性に関するdocコメント
bar = 1
baz = 2
"""Foo.baz属性に関するdocstring"""
バージョン 0.6 で変更: autodataとautoattribute がdocstringにも対応しました。
ノート
もしもデコレータのついた関数やメソッドのドキュメントを生成する場合には、autodocが、実際にモジュールをインポートして、指定された関数やメソッドの__doc__属性を見てドキュメントを生成しているということに注意してください。これは、もしデコレートされた関数が他のものに置き換えられる場合には、元の__doc__の内容を新しい関数にもコピーしなければ動作しないということを意味しています。
Python 2.5以降であれば、functools.wraps()を使用することで、このあたりまできちんと面倒を見てくれます。
autodoc拡張には、新しい設定値がいくつかあります。
この値を指定することで、本体のautoclassディレクティブにどの内容を追加するのかを選択することができます。指定可能な値は以下の通りです:
バージョン 0.3 で追加.
autodocは以下のイベントを追加で提供します:
バージョン 0.4 で追加.
autodocがdocstringを読み込んで処理をするタイミングで呼び出されます。linesは処理されたdocstringが入っている、文字列のリストです。このリストはイベントハンドラの中で変更することができ、この結果を利用します。
| パラメタ: |
|
|---|
バージョン 0.5 で追加.
autodocがオブジェクトのシグニチャをフォーマットしているときに呼び出されます。イベントハンドラは新しいタプル(signature, return_annotation)を返すことができ、Sphinxはこの出力を使ってドキュメントを生成します。
| パラメタ: |
|
|---|
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では以下のイベントを発行することで、指定されたメンバーをドキュメントに含めるかどうかをユーザが決定できるようになっています:
バージョン 0.5 で追加.
autodocがメンバーをドキュメントに含めるかどうかを決定するときに呼ばれます。もしもこのハンドラーがTrueを返すとメンバーのドキュメントははずされます。Falseを返すと含まれるようになります。
| パラメタ: |
|
|---|