New in version 1.0.
当初、Sphinxは一つのプロジェクトと、Pythonの言語のドキュメントのために作られました。その後少し経って、汎用的なドキュメントツールとして作り直されましたが、Pythonモジュールのドキュメントのため、という部分はツールの奥深くまで根を伸ばしたままでした。 function などのもっとも基本的なディレクティブは、Pythonのオブジェクトのために設計されました。しばらくたって、Sphinxはいくらか人気が出てきて、C/C++のプロジェクト、JavaScript, reStructuredText(このドキュメントのように)など、さまざまな異なる目的で使用したい、という要求が出てきました。
今までも書けないことはありませんでしたが、1.0からは、もっと簡単に、Sphinxでサポートしていない異なるプログラミング言語を使用したプロジェクトのドキュメントでも使える用になりました。 ドメイン という機能がこれを可能にします。
ドメインというのは、説明のためのマークアップ(reStructuredTextの ディレクティブ と ロール)と、プログラミング言語の構成部品と関連する オブジェクト へのリンクによってできています。ドメインに属するディレクティブとロール名は py:function などのように、 ドメイン:名前: という名前を持ちます。ドメインを使って、Pythonのモジュール索引のような、専用の索引を作成することもできます。
ドメインがあるということは、C++とPythonの両方のクラスに言及したいようなドキュメントを書く場合でも、名前が衝突する問題がない、ということです。まったく新しい言語のドキュメントをサポートするのも簡単になります。
このセクションでは、Sphinxのドメインが何を提供するのか、ということを説明していきます。ドキュメントAPIの説明は ドメインAPI で説明します。
ほとんどのドメインは、いくつかの object description directives を提供しています。これを使って、モジュールが提供する特定のオブジェクトについて説明をしていきます。それぞれのディレクティブでは、何について説明しているか、説明すべき内容などの基本情報のためのフォーマットや統一のルールを定めています。基本的なスタイルのディレクティブは、全体の索引に、説明対象へのリンクを追加しますが、もし索引に追加したくなければ、ディレクティブのオプションフラグに :noindex: を追加します。例えば、Pythonのドメインのディレクティブの場合には、次のようになります:
.. py:function:: spam(eggs)
ham(eggs)
:noindex:
Spam or ham the foo.
ドメインは、オブジェクトへのリンクを張るためのロールも提供します。例えば先ほどのサンプルの関数説明にリンクを張るためには、次のように書きます:
関数 :py:func:`spam` は同じ処理を行います。
このように、ディレクティブとロール名の両方とも、ドメイン名とディレクティブ名の２つから構成されています。
デフォルトドメイン
もし、Pythonしか登場しないプロジェクトで、Pythonオブジェクトの説明しか書かない場合に、ドメイン名を毎回書かなくても良いようにする機能が提供されています。 primary_domain 設定値と、専用のディレクティブの2つの方法で、デフォルトのドメインを指定できるようになっています。
新しいデフォルトのドメインを設定します。 primary_domain はプロジェクト全体のデフォルトを決定しますが、このディレクティブは同じファイル内にのみ影響を与えます。
もしもデフォルトが設定されないと、Pythonドメイン(py)がデフォルトになります。これは、過去のバージョンのSphinxで書かれたドキュメントと互換性があります。
デフォルトドメインに属するディレクティブとロールを書く場合には、ドメイン名を入れる必要はありません:
.. function:: pyfunc()
Pythonの関数の説明
:func:`pyfunc` への参照。
汎用的なクロスリファレンスのために使用されるのと同じような機能を持つ、クロスリファレンスのためのロールが、ドメインによって提供されます。詳しくは クロスリファレンス文法 を参照してください。
簡単に説明すると:
Pythonドメイン(py)では、モジュールの説明のために、次のようなディレクティブを提供しています:
このディレクティブはモジュールの説明の開始時に使用します。パッケージやサブモジュールにも使用できますが、この場合はパッケージ名を含む、完全な名前を指定してください。この ディレクティブは py:class ディレクティブのようなコンテンツを作成することはできません。
このディレクティブを使用すると、グローバルなモジュール索引に項目が追加されます。
platform オプションが存在していれば、そのモジュールが利用可能なモジュールをカンマ区切りで指定します。もしすべてのプラットフォームで利用可能であれば、このオプションは使用しないようにしましょう。プラットフォーム名としては、短い識別子、例えば、”IRIX”, “Mac”, “Windows”, “Unix”などから利用してください。もし適用時点ですでに使用されているキーがあれば、それを使用してください。
synopsis オプションには、モジュールの目的を説明する文章を書くことができます。現在のバージョンでは、これはグローバルモジュールインデックスの中でのみ使用されます。
deprecated オプションを使用すると、このモジュールが古くて、使用するのを推奨しない、ということを示すことができます。オプションは取りません。このディレクティブは様々な場所で使用されるでしょう。
このディレクティブはSphinxに対して、この行以降のクラスや関数などが、指定された与えられたモジュール (py:module のように)の中にある、ということを通知します。これを使用しても、索引のエントリーは作成されません。 mod へのリンクターゲットも作成されません。このディレクティブは、モジュールに含まれる項目へのドキュメントが様々なファイルやセクションに分割されている場合に便利です。この場合には一カ所だけ py:module ディレクティブを使用して、他の箇所で py:currentmodule を使用するようにします。
モジュールとクラスの中の構成要素を記述するために、次のようなディレクティブが提供されています:
モジュール内のグローバルなデータの説明をします。変数も値も”定義された定数”として取り込むことができます。クラスとオブジェクトの属性はこの環境を使用してドキュメントを書くことはできません。
例外クラスの説明をします。シグニチャには、コンストラクタの引数を括弧付きで含めることもできますが、しなくてもかまいません。
モジュールレベル関数の説明です。シグニチャはパラメータを含めます。オプションのパラメータに対してはカッコでくくります。分かりやすさを上げる目的でデフォルト値を入れることもできます。 Pythonシグニチャ の説明も参照してください。サンプル:
.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
オブジェクトのメソッドはこのディレクティブではドキュメントを記述することはできません。モジュールの名前空間にあり、モジュールの公開インタフェースとして作成されているメソッドに限って使用することができます。これらは通常の関数とほぼ同じように使用できます。
説明にはパラメータに必要な関する情報と、それらがどのように使用されるのか(変更可能なオブジェクトが渡されたときに、変更されるのかどうか)、副作用、投げられる可能性のある例外の情報を含まなければなりません。小さいサンプルが提供されるでしょう。
クラスについて説明します。シグニチャにはコンストラクタ引数になるパラメータも含めることができます。 Pythonシグニチャ も参照してください。
このクラスに属する属性とメソッドのディレクティブはこのディレクティブの本体の中に記述します。このクラスの外に書いた場合は、提供された名前にクラス名が含まれていれば、クロスリファレンスは動作します。サンプル:
.. class:: Foo
.. method:: quux()
-- あるいは --
.. class:: Bar
.. method:: Bar.quux()
最初の書き方が推奨です。
オブジェクトの属性のデータの説明をします。この説明には期待されるデータの型、値を直接変更することができるかどうか、という情報を含めます。
オブジェクトのメソッドの説明をします。パラメータからは self パラメータははずします。この説明には function と同じ情報を記述するようにします。 Pythonシグニチャ も参照してください。
py:method とほぼ一緒ですが、メソッドがスタティックメソッドであるということを表します。
New in version 0.4.
関数やメソッド、クラスのコンストラクタのシグニチャは、オプションパラメータにカッコを使うのを除き、Pythonで書くように記述することができます:
.. py:function:: compile(source[, filename[, symbol]])
このような省略可能な引数を表す場合には、慣習的にカンマの前に開きカッコを置きます。省略できる引数が二つ以上ある場合には、カッコを入れ子にするスタイルと、フラットにするスタイルの両方があります。このような場合にはほとんどの場合、オプションの引数は個別に与えることができます:
.. py:function:: compile(source[, filename, symbol])
オプション引数のデフォルト値を与えることもできます。ただし、値にカンマが含まれると、シグニチャのパーサはうまく動作しません。Pythonの３つのスタイルの引数のアノテーションと同様に、返り値の型も記述することができます:
.. py:function:: compile(source : string[, filename, symbol]) -> ast object
New in version 0.4.
Pythonのオブジェクト説明のためのディレクティブの内側には、適切に情報が明示されて、決まったルールに従ったreSTフィールドを配置することができます:
フィールドは、 return, rtype 以外の場合は、上記のキーワードのうち、どれかと、引数を一つが引数として設定されています。 return, rtype だけは引数を取りません。サンプルを見ていただくのが一番でしょう:
.. function:: format_exception(etype, value, tb[, limit=None])
トレースバック付きで、例外を人の読める形式にフォーマットします。
:param etype: 例外のタイプ
:param value: 例外オブジェクト
:param tb: トレースバックオブジェクト
:param limit: 表示するスタックフレームの数の最大数
:type limit: 数値 or None
:rtype: 文字列のリスト
型情報が一語で表せる場合には、属性の型と説明をひとつにまとめることもできます:
:param integer limit: 表示するスタックフレームの数の最大数
これは次のようにレンダリングされます:
- format_exception(etype, value, tb[, limit=None])
トレースバック付きで、例外を人の読める形式にフォーマットします。
Parameters:
- etype – 例外のタイプ
- value – 例外オブジェクト
- tb – トレースバックオブジェクト
- limit (数値 or None) – 表示するスタックフレームの数の最大数
Return type: 文字列のリスト
以下のロールを使用すると、モジュール内のオブジェクトを参照することができます。一致する識別子が見つかれば、ハイパーリンクが作成されます:
モジュールへの参照です。ドットで区切られた名前も使用できます。これはパッケージ名としても利用可能です。
Pythonの関数への参照です。ドットで区切られた名前も使用できます。ロールのテキストは読みやすさのために括弧を後ろに含める必要はありません。 add_function_parentheses 設定値をtrue(デフォルト)にしておくと、Sphinxが自動で括弧を追加します。
モジュール変数を参照します。
定義済みの定数への参照です。これはC言語の #define や、 Pythonで変更されることのない変数に使います。
クラス名です。ドットで区切られた名前も使用できます。
オブジェクトのメソッドへの参照です。ロールのテキストには型名とメソッド名を含めなければなりません。ただし、型の記述中に書く場合には省略することもできます。ドットで区切られた名前も使用できます。
オブジェクトの属性への参照です。
例外への参照です。ドットで区切られた名前も使用できます。
型が指定されていないオブジェクトの名前です。 default_role 一緒に使用すると便利です。
New in version 0.4.
このマークアップの中の名前には、モジュール名, クラス名なども含めることができます。例えば、 :py:func:`filter` は現在のモジュールに定義されている filter という名前の関数か、その名前を持つ組み込み関数をあらわします。 :py:func:`foo.filter` と明示的に書くと、 foo モジュールの中の filter 関数を表します。
通常、これらのロールで使用される名前は、最初は修飾子なしで検索されます。次に現在のモジュール名を前に付けて検索されます。その次に現在のモジュール名とクラス名(あれば)を付けて検索されます。もし、ドットが先頭についた名前が指定された場合には、この探索順は逆になります。例えば、 codecs というPythonモジュールの定義の中で :py:func:`open` が定義されると、常に組み込み関数を参照しますが、 :py:func:`.open` と書かれると、 codecs.open() を参照するようになります。
また、名前の前にドットがついていて、正確に一致するものがないと、ドットを外した名前を持つオブジェクトと、その名前を末尾に含むすべてのオブジェクトが検索されます。例えば、 :py:meth:`.TarFile.close` という文字列は、現在のモジュールが tarfile でなかったとしても、 tarfile.TarFile.close() を見つけ出して参照します。もしも該当するオブジェクトが複数ある場合には、どれを参照すればいいのか一意に定まらないため、Sphinxは警告を出します。
属性名が、現在のクラスのものかどうかを決定するのにも、同様の名前検索の仕組みが使用されます。
C言語ドメイン(c)はC言語のAPIのドキュメントを書くのに適しています。
Cの関数の説明に使用します。シグニチャはC言語内で書かれる様に記述します。例えば以下のように書きます:
.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
これは、関数のようなプリプロセッサマクロにも使用することができます。説明の中で使用されることもあるため、引数名も書く必要があります。
シグネチャ内のアスタリスクはバックスラッシュでエスケープする必要はありません。この中はreSTの行内のテキスト処理のパーサは実行されず、専用のパーサで処理されます。
C言語の構造体メンバーの説明をします。以下のように記述します:
.. c:member:: PyObject* PyTypeObject.tp_bases
説明のテキストには受け入れ可能な値の範囲、値がどのように解釈されるべきか、値が変更可能かどうかという情報を入れるべきです。構造体のメンバーへの参照をテキストの中で書きたい場合には、 member ロールを使用すべきです。
シンプルなC言語のマクロの説明をします。シンプルなマクロというのは、単純なコード展開だけをするもので、引数を取らないものです。また、単純な定数定義にも使用しません。このディレクティブのサンプルを見るには、Pythonドキュメントの PyObject_HEAD, Py_BEGIN_ALLOW_THREADS を参照してください。
C言語の型名を説明します。型というのは、typedefかstructで定義されるものです。シグニチャには型名を指定します。
グローバルなC言語の変数について説明します。シグニチャは型を含む必要があります。次のように記述します:
.. c:var:: PyObject* PyClass_Type
C++ドメインは(cpp)は、C++プロジェクトのドキュメント作成をサポートします。
次のようなディレクティブが利用可能です:
C++オブジェクトの説明をします。完全なシグニチャ定義をサポートしています。C++の宣言部で使用するようにシグニチャを書くことができます。いくつかサンプルを提示します:
.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
パラメータと型情報付きのメソッドの説明です。
.. cpp:function:: bool namespaced::theclass::method(arg1, arg2)
型情報なしのメソッドの説明です。
.. cpp:function:: const T &array<T>::operator[]() const
テンプレート配列のconstのインデックス操作メソッドの説明です。
.. cpp:function:: operator bool() const
これはキャスト演算子の説明です。
.. cpp:member:: std::string theclass::name
.. cpp:type:: theclass::const_iterator
これらのディレクティブは、次のようにレンダリングされます:
- bool namespaced::theclass::method(int arg1, std::string arg2)¶
パラメータと型情報付きのメソッドの説明です。
- bool namespaced::theclass::method(arg1 None, arg2 None)¶
型情報なしのメソッドの説明です。
- const T& array<T>::operator[]() const¶
テンプレート配列のconstのインデックス操作メソッドの説明です。
- operator bool() const¶
これはキャスト演算子の説明です。
- std::string theclass::name¶
- type theclass::const_iterator¶
ドキュメントの中で、この行以降で説明するオブジェクトが所属するC++の名前空間を選択します。
このドメインは次のようなオブジェクトの種類へのロールを提供しています:
C++オブジェクトへの参照です。完全なシグニチャを指定することができます。オーバーロードされた関数へのリンクを張る場合には、完全なシグニチャを指定する必要があります。
参照に関する注意点
現在の実装では、オーバーロードされた特定のメソッドに対してリンクを張ることはできません。C++ドメインは、オーバーロードされたメソッドを持つ言語をサポートする最初のドメインです。きちんとそれぞれのメソッドを比較できるようなデータ構造を持つまでは、特定のメソッドを参照するために見難い構文を導入するのは避けたいと考えています。現在のSphinxでは、オーバーロードされた最初のメソッドや関数をリンクしに行きます。
標準ドメインには、固有のドメインを作るまでもないすべてのマークアップが含まれます。これらのディレクティブやロールには、ドメイン名のプリフィックスは付きません。
標準ドメインには、 add_object_type() APIを使って追加されたカスタムの説明ディレクティブ、ロールも含まれます。
現在は、コマンドラインのプログラムを説明するためのディレクティブ群が提供されています:
コマンドラインオプションやスイッチの説明をします。オプションの引数名は不等号でくくる必要があります:
.. option:: -m <モジュール>, --module <モジュール>
モジュールをスクリプトとみなして実行します
このディレクティブは 最初 のオプションを名前付きのターゲットとみなして、クロスリファレンスを作成します。これは option にて参照可能です。このサンプルの場合は、 :option:`-m` という形式でリンクを張ることができます。
py:currentmodule と同様に、このディレクティブは何も出力しません。その代わりにこのディレクティブを定義すると、Sphinxはこの後に定義される option ディレクティブが説明するオプションが、ここで指定された 名前 を持つプログラムに属するということを認識できるようになります。
program を使用する場合には、 option ロールとプログラム名を適合させる必要があります。以下のような状況について見てみます:
.. program:: rm
.. option:: -r
再帰的に動作するようになります
.. program:: svn
.. option:: -r revision
作業中のワークに対してリビジョンを設定します
この場合、 option`rm -r` 最初のオプションを示し、 option:`svn -r` は２番目のオプションを示します。
プログラム名はスペースを含むこともできます。そのため、 svn add や、 svn commit などのサブコマンドを個別に取り扱いたい、というケースにも対応できます。
New in version 0.5.
どこのドメインにも属さないような、非常に汎用的なオブジェクトの説明用のディレクティブも存在します:
JavaScriptドメイン(js)は次のようなディレクティブを提供します:
JavaScriptの関数やメソッドの説明をします。オプショナルな引数を説明したい場合には、Pythonシグニチャのために 説明したように 角カッコを使用します。
引数や期待される型、関数から投げられるエラー、returnで返される値などのフィールド情報の詳細を書くこともできます:
.. js:function:: $.getJSON(href, callback[, errback])
:param string href: リソースのある場所を示すURI
:param callback: GETの応答が帰ってきたときに呼ばれるオブジェクトを受け取るコールバック
:param errback:
リクエストにエラーが発生したときに、呼ばれるコールバック。
このように多くの情報が必要なら複数行にかけて書くこともできます。
:throws SomeError: エラーが発生する理由
:returns: 何か
次のようにレンダリングされます:
- $.getJSON(href, callback[, errback])¶
Arguments:
- href (string) – リソースのある場所を示すURI
- callback – GETの応答が帰ってきたときに呼ばれるオブジェクトを受け取るコールバック
- errback – リクエストにエラーが発生したときに、呼ばれるコールバック。 このように多くの情報が必要なら複数行にかけて書くこともできます。
Throws SomeError: エラーが発生する理由
Returns: 何か
オブジェクトを作るコンストラクタの説明をします。基本的には関数と似ていますが、 class という文字が表示されます:
.. js:class:: MyAnimal(name[, age])
:param string name: 動物の名前
:param number age: 動物の年齢(オプション)
これは次のようにレンダリングされます:
- class MyAnimal(name[, age])¶
Arguments:
- name (string) – 動物の名前
- age (number) – 動物の年齢(オプション)
グローバル変数や定数の説明です。
オブジェクト の持つ 属性名 を説明します。
このドメインでは、オブジェクトの説明を参照する、次のようなロールが提供されています:
reStructuredTextドメイン(rst)は、次のようなディレクティブを提供します:
reSTディレクティブの説明をします。 name には単独のディレクティブ名か、引数付きの実際のディレクティブの文法(.. を前に付けたり、後ろに :: を付けたり)で記述をします。
サンプル:
.. rst:directive:: foo
Fooの説明
.. rst:directive:: .. bar:: baz
Barの説明
これは次のようにレンダリングされます
- .. foo::¶
Fooの説明
- .. bar:: baz¶
Barの説明
説明したオブジェクトを参照するために、次のようなロールが提供されます:
sphinx-contrib リポジトリに、拡張機能として利用可能なドメインがいくつかあります。現在はRubyとErlangのドメインがあります。