docstringからのドキュメントの取り込み¶この拡張機能は、docstringでドキュメントが書かれているモジュールをインポートして、そのdocstringから、半自動的にドキュメントを取り込みます。注釈Sphinx(実際にはSphinxを実行しているPythonインタプリタ)がモジュールを見つけるためには、そのモジュールはインポート可能になっていなければなりません。これは、インポートしたいモジュールやパッケージがsys.pathで設定されているディレクトリのどれかに入っている必要があるということです。設定ファイル内で、適宜sys.pathを調整してください。条件により保護されていることを確認して下さい。この機能をうまく働かせるためには、docstringは正しいreStructuredTextのフォーマットに従って記述されている必要があります。すべてのSphinxのマークアップをdocstringの中に書くことができ、最終的に正しくドキュメンテーションされます。手書きのドキュメントと一緒にモジュールのドキュメントを作成する場合には、純粋なAPIのドキュメントを同時に自動生成できるため、この機能を使うことで両方を同時に管理する苦痛が軽減されます。py:classなどのディレクティブに似た別バージョンのディレクティブを提供します。py:classディレクティブと一緒に差込みます。注釈py:classを宣言したときに、既に定義されているpy:moduleの中に配置されるのと同様に、autoclassも同じように振舞います。py:classについても同様です。autoexception::¶モジュール、クラス、例外のドキュメントを作成します。docstring."auto"ディレクティブは、取り込むだけでなく、自分自身のコンテンツを書くことができます。自動取り込みされたドキュメントの後に挿入されます。:members:このように書くと、すべてのモジュールのメンバーを(再帰的に)ドキュメントにしていきます。:members:これをビルドすると、すべての非プライベートの関数とプロパティ(名前が_以外から始まる)のドキュメントが取り込まれます。フラグをセットすると含まれるようになります。:special-members:このようにセットすると、クラスのプライベートメンバー、特殊メンバーの両方が出力されるようになります。オプションは引数を持てるようになりました。始まるメンバーをドキュメントしたい場合などに指定します。:inherited-members:このフラグとundoc-membersを同時に適用すると、クラスとモジュールの持っている、すべての利用可能なメンバーのドキュメントが作成されるようになります。docstringがreST形式でないモジュールで定義されたメンバーがあると、マークアップエラーになるでしょう。eat(persona)この機能はデコレータなどによって、メソッドの呼び出し規約が内省機能で取れない状態になっている場合に便利です。追加.automoduleと、autoclass、autoexceptionディレクティブはshow-inheritanceというオプションをサポートしています。これが設定されると、クラスのシグニチャの直前に、継承しているベースクラスのリストが表示されるようになります。automoduleに対して使用すると、モジュール内でドキュメントが記述されているすべてのクラスのベースクラスが表示されるようになります。追加.autodocのすべてのディレクティブはnoindexというフラグオプションをサポートしています。これは標準のpy:functionなどと同様の効果があります。ドキュメントが生成されるオブジェクトと、それに含まれるメンバーに対する索引が生成されなくなります。deprecatedオプションをサポートしています。追加.automoduleとautoclassはmember-orderというオプションを持っています。これを設定すると、このディレクティブの中でのみグローバルなautodoc_member_orderという設定をオーバーライドできます。追加.メンバーのドキュメント生成をサポートしているディレクティブはexclude-membersというオプションも持っています。これはすべてのドキュメントを生成する場合に、除外したいメンバーの名前をひとつだけ追加するのに使用します。追加.membersオプションが設定されているautomoduleディレクティブの中では、__module__属性がautomoduleで与えられたモジュール名と等しいメンバーのみのドキュメントが生成されます。これはインポートされたクラスや関数のドキュメントまで生成しないための措置です。オプションによって、この動作をさせないよう指定でき、全てのメンバーをドキュメント化します。インポートしたモジュールの属性はドキュメント化されないことに注意してください。これは、属性のドキュメント化は現在のモジュールのソースコードをパースして行うためです。内のモジュールリストを追加します。autoattribute::¶これらのディレクティブはautoclassなどと同じように動作しますが、メンバー内のドキュメント生成のオプションはありません。中にドキュメンテーションを入れることができます。後者の形式は1行のみに制限されます。docstringにも対応しました。代入文の直後にコメントドキュメントを書けるようになりました。オプションがあります。added.注釈もしもデコレータのついた関数やメソッドのドキュメントを生成する場合には、autodocが、実際にモジュールをインポートして、指定された関数やメソッドの__doc__属性を見てドキュメントを生成しているということに注意してください。これは、もしデコレートされた関数が他のものに置き換えられる場合には、元の__doc__の内容を新しい関数にもコピーしなければ動作しないということを意味しています。2.5以降であれば、functools.wraps()を使用することで、このあたりまできちんと面倒を見てくれます。set:autoclass_content¶この値を指定することで、本体のautoclassディレクティブにどの内容を追加するのかを選択できます。指定可能な値は以下の通りです:"class"クラスのdocstringだけが挿入されます。これがデフォルトの動作になります。automethodを使用するか、autoclassに対してmembersオプションを設定することで、__init__の内容は別のメソッドとしてドキュメント化できます。"both"クラスのdocstringと、__init__メソッドのdocstringの両方が結合されて挿入されます。"init"__init__メソッドのdocstringだけが挿入されます。メソッドのドックストリングが代わりに使用されます。追加.autodoc_member_order¶これの設定を変更することで、ドキュメントのついたメンバーをアルファベット順にソートするか('alphabetical')、もしくはメンバーのタイプによって('groupwise')ソートするか、ソースコードの定義順('bysource')にソートするかを変更できます。デフォルトはアルファベット順です。ソースコードの定義順を指定する場合には、対象のモジュールはPythonモジュールで、ソースコードが利用できるようになっていなければなりません。'imported-members'.autodoc_docstring_signature¶Cモジュールからインポートされた関数は、情報を取得できないため、これらの関数に関するシグニチャを自動的に決定することはできません。これを使用すると、これらの関数のdocstringの最初の行に、これらの関数のシグニチャを入れられます。(デフォルト)にすると、autodocは関数やメソッドのdocstringの最初の行を見て、もしシグニチャのような情報が書かれていたら、その行をシグニチャとして読み込み、docstringからはその行の内容を削除して扱います。追加.autodocがdocstringを読み込んで処理をするタイミングで呼び出されます。linesは処理されたdocstringが入っている、文字列のリストです。このリストはイベントハンドラの中で変更でき、この結果を利用します。ディレクティブに与えられたオプションです。属性をもったオブジェクトです。同じ名前のフラグオプションが渡されるとtrueになります。docstringの行数。追加.autodocがオブジェクトのシグニチャをフォーマットしているときに呼び出されます。return_annotation)を返すことができ、Sphinxはこの出力を使ってドキュメントを生成します。ディレクティブに与えられたオプションです。属性をもったオブジェクトです。同じ名前のフラグオプションが渡されるとtrueになります。