Sphinxドメイン

バージョン 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)

   Spam or ham the foo.

ここでは、 spamham という2つのPython関数を説明しています。もしシグニチャが長すぎる場合には、バックスラッシュを使って引数リストの中で改行できます:

.. py:function:: filterwarnings(action, message='', category=Warning, \
                                module='', lineno=0, append=False)
   :noindex:

(このサンプルは、 :noindex: フラグの使い方でもあります)。

ドメインは、オブジェクトへのリンクを張るためのロールも提供します。例えば先ほどのサンプルの関数説明にリンクを張るためには、次のように書きます:

The function :py:func:`spam` does a similar thing.

このように、ディレクティブとロール名の両方とも、ドメイン名とディレクティブ名の2つから構成されています。

デフォルトドメイン

もし、Pythonしか登場しないプロジェクトで、Pythonオブジェクトの説明しか書かない場合に、ドメイン名を毎回書かなくても良いようにする機能が提供されています。 primary_domain 設定値と、専用のディレクティブの2つの方法で、デフォルトのドメインを指定できるようになっています。

.. default-domain:: name

新しいデフォルトのドメインを設定します。 primary_domain はプロジェクト全体のデフォルトを決定しますが、このディレクティブは同じファイル内にのみ影響を与えます。

もしもデフォルトが設定されないと、Pythonドメイン(py)がデフォルトになります。これは、過去のバージョンのSphinxで書かれたドキュメントと互換性があります。

デフォルトドメインに属するディレクティブとロールを書く場合には、ドメイン名を入れる必要はありません:

.. function:: pyfunc()

   Describes a Python function.

Reference to :func:`pyfunc`.

クロスリファレンス文法

汎用的なクロスリファレンスのために使用されるのと同じような機能を持つ、クロスリファレンスのためのロールが、ドメインによって提供されます。詳しくは クロスリファレンス文法 を参照してください。

簡単に説明すると:

  • 明示的なリンク名と、リンクターゲットを指定できます。 :rst:role:`タイトル <ターゲット>` と書くと、 ターゲット を参照しますが、リンクテキストは タイトル になります。

  • 用語の先頭の文字に ! を指定すると、参照もハイパーリンクも作成されなくなります。

  • 用語の先頭の文字に ~ を設定すると、リンクテキストは最後の項目だけが表示されるようになります。例えば、 :py:meth:`~Queue.Queue.get` というマークアップがあったとすると、 Queue.Queue.get に対して参照が作成されますが、リンクテキストとしては get が表示されます。

Pythonドメイン

Pythonドメイン(py)では、モジュールの説明のために、次のようなディレクティブを提供しています:

.. py:module:: name

このディレクティブはモジュールの説明の開始時に使用します。パッケージやサブモジュールにも使用できますが、この場合はパッケージ名を含む、完全な名前を指定してください。この ディレクティブは py:class ディレクティブのようなコンテンツを作成することはできません。

このディレクティブを使用すると、グローバルなモジュール索引に項目が追加されます。

platform オプションが存在していれば、そのモジュールが利用可能なモジュールをカンマ区切りで指定します。もしすべてのプラットフォームで利用可能であれば、このオプションは使用しないようにしましょう。プラットフォーム名としては、短い識別子、例えば、”IRIX”, “Mac”, “Windows”, “Unix”などから利用してください。もし適用時点ですでに使用されているキーがあれば、それを使用してください。

synopsis オプションには、モジュールの目的を説明する文章を書くことができます。現在のバージョンでは、これはグローバルモジュールインデックスの中でのみ使用されます。

deprecated オプションを使用すると、このモジュールが古くて、使用するのを推奨しない、ということを示すことができます。オプションは取りません。このディレクティブは様々な場所で使用されるでしょう。

.. py:currentmodule:: name

このディレクティブはSphinxに対して、この行以降のクラスや関数などが、指定された与えられたモジュール (py:module のように)の中にある、ということを通知します。これを使用しても、索引のエントリーは作成されません。 py:mod へのリンクターゲットも作成されません。このディレクティブは、モジュールに含まれる項目へのドキュメントが様々なファイルやセクションに分割されている場合に便利です。この場合には一カ所だけ py:module ディレクティブを使用して、他の箇所で py:currentmodule を使用するようにします。

モジュールとクラスの中の構成要素を記述するために、次のようなディレクティブが提供されています:

.. py:function:: name(parameters)

モジュール レベルの関数について説明します。署名はPython の関数定義で指定されたパラメーターを含む必要があります。 Pythonシグニチャ を参照ください。

.. py:function:: Timer.repeat(repeat=3, number=1000000)

メソッドには py:method を使用します。

説明には一般的に、パラメータに必要な関する情報と、それらがどのように使用されるのか(変更可能なオブジェクトが渡されたときに、変更されるのかどうか)、副作用、投げられる可能性のある例外の情報を含めます。

この情報は 詳細情報フィールドのリスト にあるデータ構造で表現できます(他のpyドメインのディレクティブでも同様です)。

.. py:data:: name

モジュール内のグローバルなデータの説明をします。変数も値も”定義された定数”として取り込むことができます。クラスとオブジェクトの属性はこの環境を使用してドキュメントを書くことはできません。

.. py:exception:: name

例外クラスの説明をします。シグニチャには、コンストラクタの引数を括弧付きで含めることもできますが、しなくてもかまいません。

.. py:class:: name
.. py:class:: name(parameters)

クラスについて説明します。シグニチャには、丸括弧とともにコンストラクタ引数として提示されるパラメータをオプションで含めることができます。 Pythonシグニチャ も参照してください。

このクラスに属する属性とメソッドのディレクティブはこのディレクティブの本体の中に記述します。このクラスの外に書いた場合は、提供された名前にクラス名が含まれていれば、クロスリファレンスは動作します。サンプル:

.. py:class:: Foo

   .. py:method:: quux()

-- or --

.. py:class:: Bar

.. py:method:: Bar.quux()

最初の書き方が推奨です。

.. py:attribute:: name

オブジェクトの属性のデータの説明をします。この説明には期待されるデータの型、値を直接変更できるかどうか、という情報を含めます。

.. py:method:: name(parameters)

オブジェクトのメソッドの説明をします。パラメータからは self パラメータははずします。この説明には function と同じ情報を記述するようにします。 Pythonシグニチャ詳細情報フィールドのリスト も参照してください。

.. py:staticmethod:: name(parameters)

py:method とほぼ一緒ですが、メソッドがスタティックメソッドであるということを表します。

バージョン 0.4 で追加.

.. py:classmethod:: name(parameters)

py:method とほぼ一緒ですが、メソッドがクラスメソッドであるということを表します。

バージョン 0.6 で追加.

.. py:decorator:: name
.. py:decorator:: name(parameters)

デコレーターを説明します。このシグニチャにはデコレーターの使い方を記述します。例えばこの関数は

def removename(func):
    func.__name__ = ''
    return func

def setnewname(name):
    def decorator(func):
        func.__name__ = name
        return func
    return decorator

次のように説明を書くことが出来ます

.. py:decorator:: removename

   Remove name of the decorated function.

.. py:decorator:: setnewname(name)

   Set name of the decorated function to *name*.

(.. py:decorator:: removename(func) とは対象的です)

これらに対応する、 py:deco といったロールはありません。代わりに、 py:func ロールを使用してください。

.. py:decoratormethod:: name
.. py:decoratormethod:: name(signature)

py:decorator とほぼ同じですが、対象がメソッドになります。

このデコレータを指定したい場合には、 py:meth ロールを使います。

Pythonシグニチャ

Pythonで書くのと同じように、関数、メソッド、クラスコンストラクタのシグニチャを与えることが出来ます。

オプション引数のデフォルト値を与えることもできます。ただし、値にカンマが含まれると、シグニチャのパーサはうまく動作しません。Pythonの3つのスタイルの引数のアノテーションと同様に、返り値の型も記述できます:

.. py:function:: compile(source : string, filename, symbol='file') -> ast object

デフォルト値を持たない省略可能なパラメータを持つ関数(よくある例としてはキーワード引数をサポートしていないC拡張モジュールで実装された関数があります)のため、省略可能な部分を角かっこで指定することも出来ます。

compile(source[, filename[, symbol]])

通常、カンマの前に開き括弧を付けます。

詳細情報フィールドのリスト

バージョン 0.4 で追加.

Pythonのオブジェクト説明のためのディレクティブの内側には、適切に情報が明示されて、決まったルールに従ったreSTフィールドを配置できます:

  • param, parameter, arg, argument, key, keyword: 引数の説明です。

  • type: 引数の型です。可能ならリンクを生成します。

  • raises, raise, except, exception: この中から投げられる例外(いつ投げられるか?)を定義します

  • var, ivar, cvar: 変数の説明をします

  • vartype: 変数の型です。可能ならリンクを生成します。

  • returns, return: 返り値の値について説明をします

  • rtype: 返り値の型です。可能ならリンクを生成します。

注釈

In current release, all var, ivar and cvar are represented as “Variable”. There is no difference at all.

フィールドは、 return, rtype 以外の場合は、上記のキーワードのうち、どれかと、引数を一つが引数として設定されています。 return, rtype だけは引数を取りません。サンプルを見ていただくのが一番でしょう:

.. py:function:: send_message(sender, recipient, message_body, [priority=1])

   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring

これは次のようにレンダリングされます:

send_message(sender, recipient, message_body[, priority=1])

Send a message to a recipient

パラメータ:
  • sender (str) – The person sending the message
  • recipient (str) – The recipient of the message
  • message_body (str) – The body of the message
  • priority (integer or None) – The priority of the message, can be a number 1-5
戻り値:

the message id

戻り値の型:

int

例外:
  • ValueError – if the message_body exceeds 160 characters
  • TypeError – if the message_body is not a basestring

型情報が一語で表せる場合には、属性の型と説明をひとつにまとめることもできます:

:param int priority: The priority of the message, can be a number 1-5

バージョン 1.5 で追加.

Container types such as lists and dictionaries can be linked automatically using the following syntax:

:type priorities: list(int)
:type priorities: list[int]
:type mapping: dict(str, int)
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]

Multiple types in a type field will be linked automatically if separated by the word “or”:

:type an_arg: int or None
:vartype a_var: str or int
:rtype: float or str

Pythonオブジェクトのクロススリファンレス

以下のロールを使用すると、モジュール内のオブジェクトを参照できます。一致する識別子が見つかれば、ハイパーリンクが作成されます:

:py:mod:

モジュールへの参照です。ドットで区切られた名前も使用できます。これはパッケージ名としても利用可能です。

:py:func:

Pythonの関数への参照です。ドットで区切られた名前も使用できます。ロールのテキストは読みやすさのために括弧を後ろに含める必要はありません。 add_function_parentheses 設定値を ``True``(デフォルト)にしておくと、Sphinxが自動で括弧を追加します。

:py:data:

モジュール変数を参照します。

:py:const:

「定義済み」定数です。変更して欲しくないPythonの変数にも使えます。

:py:class:

クラス名です。ドットで区切られた名前も使用できます。

:py:meth:

オブジェクトのメソッドへの参照です。ロールのテキストには型名とメソッド名を含めなければなりません。ただし、型の記述中に書く場合には省略もできます。ドットで区切られた名前も使用できます。

:py:attr:

オブジェクトの属性への参照です。

:py:exc:

例外への参照です。ドットで区切られた名前も使用できます。

:py:obj:

型が指定されていないオブジェクトの名前です。 default_role 一緒に使用すると便利です。

バージョン 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は警告を出します。

~. をオブジェクトの識別子の前に組み合わせることができます。 :py:meth:`~.TarFile.close` と指定されると、 tarfile.TarFile.close() が参照されますが、実際に文章中に表示されるのは、 close() となります。

C言語ドメイン

C言語ドメイン(c)はC言語のAPIのドキュメントを書くのに適しています。

.. c:function:: type name(signature)

Cの関数の説明に使用します。シグニチャはC言語内で書かれる様に記述します。例えば以下のように書きます:

.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

これは、関数のようなプリプロセッサマクロにも使用できます。説明の中で使用されることもあるため、引数名も書く必要があります。

シグネチャ内のアスタリスクはバックスラッシュでエスケープする必要はありません。この中はreSTの行内のテキスト処理のパーサは実行されず、専用のパーサで処理されます。

.. c:member:: type name

C言語の構造体メンバーの説明をします。以下のように記述します:

.. c:member:: PyObject* PyTypeObject.tp_bases

説明のテキストには受け入れ可能な値の範囲、値がどのように解釈されるべきか、値が変更可能かどうかという情報を入れるべきです。構造体のメンバーへの参照をテキストの中で書きたい場合には、 member ロールを使用すべきです。

.. c:macro:: name

「シンプルな」C言語のマクロの説明をします。シンプルなマクロというのは、単純なコード展開だけをするもので、引数を取らず、そのため関数として説明できないものです。これはC言語の単純な #define です。このディレクティブのサンプルを見るには、Pythonドキュメントの PyObject_HEADPy_BEGIN_ALLOW_THREADS を参照してください。

.. c:type:: name

C言語の型名を説明します。型というのは、typedefかstructで定義されるものです。シグニチャには型名を指定します。

.. c:var:: type name

グローバルなC言語の変数について説明します。シグニチャは型を含む必要があります。次のように記述します:

.. c:var:: PyObject* PyClass_Type

C言語の要素へのクロスリファレンス

以下のロールは、もしドキュメントの中に定義の説明があれば、C言語の要素へのクロスリファレンスを作成します:

:c:data:

C言語の変数への参照です。

:c:func:

C言語の関数への参照です。カッコを省略することはできません。

:c:macro:

前の説明で述べた、シンプルなC言語のマクロへの参照です。

:c:type:

C言語の型への参照です。

C++ドメイン

C++ドメインは(cpp)は、C++プロジェクトのドキュメント作成をサポートします。

以下のディレクティブを使用できます。全ての定義にはアクセス制御識別子(public, private, protected)を最初に付けられます。

.. cpp:class:: class specifier

クラスや構造について説明します。継承についての情報も書けます。

.. cpp:class:: MyClass : public MyBase, MyOtherBase

クラスはネストしたスコープの中で直接宣言することができます、 例として

.. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase

テンプレートクラスは次のように宣言が可能です:

.. cpp:class:: template<typename T, std::size_t N> std::array

もしくは改行を用いて:

.. cpp:class:: template<typename T, std::size_t N> \
               std::array

完全な、もしくは一部のテンプレートの専門化は次のように宣言できます:

.. cpp:class:: template<> \
                std::array<bool, 256>

.. cpp:class:: template<typename T> \
                std::array<T, 42>
.. cpp:function:: (member) function prototype

関数とメンバーの説明です。例えば以下のように書きます:

.. cpp:function:: bool myMethod(int arg1, std::string arg2)

   A function with parameters and types.

.. cpp:function:: bool myMethod(int, double)

   A function with unnamed parameters.

.. cpp:function:: const T &MyClass::operator[](std::size_t i) const

   An overload for the indexing operator.

.. cpp:function:: operator bool() const

   A casting operator.

.. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept

   A constexpr function.

.. cpp:function:: MyClass::MyClass(const MyClass&) = default

   A copy constructor with default implementation.

Functionテンプレートは次のようにも表現できます:

.. cpp:function:: template<typename U> \
                  void print(U &&u)

and function template specialisations:

.. cpp:function:: template<> \
                  void print(int i)
.. cpp:member:: (member) variable declaration
.. cpp:var:: (member) variable declaration

変数とメンバー変数の説明です。例えば以下のように書きます:

.. cpp:member:: std::string MyClass::myMember

.. cpp:var:: std::string MyClass::myOtherMember[N][M]

.. cpp:member:: int a = 42

変数テンプレートは次のようにも表現できます:

.. cpp:member:: template<class T> \
                constexpr T pi = T(3.1415926535897932385)
.. cpp:type:: typedef declaration
.. cpp:type:: name
.. cpp:type:: type alias declaration

Describe a type as in a typedef declaration, a type alias declaration, or simply the name of a type with unspecified type, e.g.,:

.. cpp:type:: std::vector<int> MyList

   A typedef-like declaration of a type.

.. cpp:type:: MyContainer::const_iterator

   Declaration of a type alias with unspecified type.

.. cpp:type:: MyType = std::unordered_map<int, std::string>

   Declaration of a type alias.

エイリアス型は次のようにも宣言が可能です:

.. cpp:type:: template<typename T> \
              MyContainer = std::vector<T>

The example are rendered as follows.

typedef std::vector<int> MyList

A typedef-like declaration of a type.

type MyContainer::const_iterator

Declaration of a type alias with unspecified type.

using MyType = std::unordered_map<int, std::string>

Declaration of a type alias.

template<typename T>
using MyContainer = std::vector<T>
.. cpp:enum:: unscoped enum declaration
.. cpp:enum-struct:: scoped enum declaration
.. cpp:enum-class:: scoped enum declaration

列挙型について説明します。型指定やスコープ指定もできます。どの列挙もスコープ無し列挙型の中に書くこともできます。例:

.. cpp:enum:: MyEnum

   An unscoped enum.

.. cpp:enum:: MySpecificEnum : long

   An unscoped enum with specified underlying type.

.. cpp:enum-class:: MyScopedEnum

   A scoped enum.

.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type

   A scoped enum with non-default visibility, and with a specified underlying type.
.. cpp:enumerator:: name
.. cpp:enumerator:: name = constant

列挙子について説明します。値指定もできます。例:

.. cpp:enumerator:: MyEnum::myEnumerator

.. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
.. cpp:concept:: template-parameter-list name
.. cpp:concept:: template-parameter-list name()

警告

The support for concepts is experimental. It is based on the Concepts Technical Specification, and the features may change as the TS evolves.

Describe a variable concept or a function concept. Both must have exactly 1 template parameter list. The name may be a nested name. Examples:

.. cpp:concept:: template<typename It> std::Iterator

   Proxy to an element of a notional sequence that can be compared,
   indirected, or incremented.

.. cpp:concept:: template<typename Cont> std::Container()

   Holder of elements, to which it can provide access via
   :cpp:concept:`Iterator` s.

They will render as follows:

template<typename It>
concept bool std::Iterator

Proxy to an element of a notional sequence that can be compared, indirected, or incremented.

template<typename Cont>
concept bool std::Container()

Holder of elements, to which it can provide access via Iterator s.

Constrained Templates

警告

The support for constrained templates is experimental. It is based on the Concepts Technical Specification, and the features may change as the TS evolves.

注釈

Sphinx does not currently support requires clauses.

Placeholders

Declarations may use the name of a concept to introduce constrained template parameters, or the keyword auto to introduce unconstrained template parameters:

.. cpp:function:: void f(auto &&arg)

   A function template with a single unconstrained template parameter.

.. cpp:function:: void f(std::Iterator it)

   A function template with a single template parameter, constrained by the
   Iterator concept.

Template Introductions

Simple constrained function or class templates can be declared with a template introduction instead of a template parameter list:

.. cpp:function:: std::Iterator{It} void advance(It &it)

    A function template with a template parameter constrained to be an Iterator.

.. cpp:class:: std::LessThanComparable{T} MySortedContainer

    A class template with a template parameter constrained to be LessThanComparable.

They are rendered as follows.

std::Iterator{It}
void advance(It &it)

A function template with a template parameter constrained to be an Iterator.

std::LessThanComparable{T}
class MySortedContainer

A class template with a template parameter constrained to be LessThanComparable.

Note however that no checking is performed with respect to parameter compatibility. E.g., Iterator{A, B, C} will be accepted as an introduction even though it would not be valid C++.

名前空間

Declarations in the C++ domain are as default placed in global scope. The current scope can be changed using three namespace directives. They manage a stack declarations where cpp:namespace resets the stack and changes a given scope. The cpp:namespace-push directive changes the scope to a given inner scope of the current one. The cpp:namespace-pop directive undos the most recent cpp:namespace-push directive.

.. cpp:namespace:: scope specification

Changes the current scope for the subsequent objects to the given scope, and resets the namespace directive stack. Note that the namespace does not need to correspond to C++ namespaces, but can end in names of classes, e.g.,:

.. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass

All subsequent objects will be defined as if their name were declared with the scope prepended. The subsequent cross-references will be searched for starting in the current scope.

Using NULL, 0, or nullptr as the scope will change to global scope.

A namespace declaration can also be templated, e.g.,:

.. cpp:class:: template<typename T> \
               std::vector

.. cpp:namespace:: template<typename T> std::vector

.. cpp:function:: std::size_t size() const

declares size as a member function of the template class std::vector. Equivalently this could have been declared using:

.. cpp:class:: template<typename T> \
               std::vector

   .. cpp:function:: std::size_t size() const

もしくは:

.. cpp:class:: template<typename T> \
               std::vector
.. cpp:namespace-push:: scope specification

Change the scope relatively to the current scope. For example, after:

.. cpp:namespace:: A::B

.. cpp:namespace-push:: C::D

the current scope will be A::B::C::D.

.. cpp:namespace-pop::

Undo the previous cpp:namespace-push directive (not just pop a scope). For example, after:

.. cpp:namespace:: A::B

.. cpp:namespace-push:: C::D

.. cpp:namespace-pop::

the current scope will be A::B (not A::B::C).

If no previous cpp:namespace-push directive has been used, but only a cpp:namespace directive, then the current scope will be reset to global scope. That is, .. cpp:namespace:: A::B is equivalent to:

.. cpp:namespace:: nullptr

.. cpp:namespace-push:: A::B

詳細情報フィールドのリスト

The C++ directives support the following info fields (see also 詳細情報フィールドのリスト):

  • param, parameter, arg, argument: パラメーターの説明です。

  • tparam: Description of a template parameter.
  • returns, return: 返り値の値について説明をします

  • throws, throw, exception: Description of a possibly thrown exception.

クロスリファレンス

These roles link to the given declaration types:

:cpp:any:
:cpp:class:
:cpp:func:
:cpp:member:
:cpp:var:
:cpp:type:
:cpp:concept:
:cpp:enum:
:cpp:enumerator:

Reference a C++ declaration by name (see below for details). The name must be properly qualified relative to the position of the link.

Note on References with Templates Parameters/Arguments

Sphinx’s syntax to give references a custom title can interfere with linking to template classes, if nothing follows the closing angle bracket, i.e. if the link looks like this: :cpp:class:`MyClass<int>`. This is interpreted as a link to int with a title of MyClass. In this case, please escape the opening angle bracket with a backslash, like this: :cpp:class:`MyClass\<int>`.

Note on References to Overloaded Functions

現在の実装では、オーバーロードされた特定のメソッドに対してリンクを張ることはできません。C++ドメインは、オーバーロードされたメソッドを持つ言語をサポートする最初のドメインです。きちんとそれぞれのメソッドを比較できるようなデータ構造を持つまでは、特定のメソッドを参照するために見難い構文を導入するのは避けたいと考えています。現在のSphinxでは、オーバーロードされた最初のメソッドや関数をリンクしに行きます。

Declarations without template parameters and template arguments

For linking to non-templated declarations the name must be a nested name, e.g., f or MyClass::f.

Templated declarations

Assume the following declarations.

class Wrapper
template<typename TOuter>
class Outer
template<typename TInner>
class Inner

In general the reference must include the template paraemter declarations, e.g., template\<typename TOuter> Wrapper::Outer (template<typename TOuter> Wrapper::Outer). Currently the lookup only succeed if the template parameter identifiers are equal strings. That is, template\<typename UOuter> Wrapper::Outer will not work.

The inner template class can not be directly referenced, unless the current namespace is changed or the following shorthand is used. If a template parameter list is omitted, then the lookup will assume either a template or a non-template, but not a partial template specialisation. This means the following references work.

(Full) Template Specialisations

Assume the following declarations.

template<typename TOuter>
class Outer
template<typename TInner>
class Inner
template<>
class Outer<int>
template<typename TInner>
class Inner
template<>
class Inner<bool>

In general the reference must include a template parameter list for each template argument list. The full specialisation above can therefore be referenced with template\<> Outer\<int> (template<> Outer<int>) and template\<> template\<> Outer\<int>::Inner\<bool> (template<> template<> Outer<int>::Inner<bool>). As a shorthand the empty template parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).

Partial Template Specialisations

Assume the following declaration.

template<typename T>
class Outer<T *>

References to partial specialisations must always include the template parameter lists, e.g., template\<typename T> Outer\<T*> (template<typename T> Outer<T*>). Currently the lookup only succeed if the template parameter identifiers are equal strings.

標準ドメイン

標準ドメインには、固有のドメインを作るまでもないすべてのマークアップが含まれます。これらのディレクティブやロールには、ドメイン名のプリフィックスは付きません。

標準ドメインには、 add_object_type() APIを使って追加されたカスタムの説明ディレクティブ、ロールも含まれます。

現在は、コマンドラインのプログラムを説明するためのディレクティブ群が提供されています:

.. option:: name args, name args, ...

コマンド ・ ライン引数またはスイッチを説明します。オプションの引数名は括弧で囲む必要があります。例えば:

.. option:: dest_dir

   Destination directory.

.. option:: -m <module>, --module <module>

   Run a module as a script.

このディレクティブは与えられた複数のオプションを名前付きのターゲットとみなし、これらはクロスリファレンスから option にて参照されます(この例の場合は :option:`dest_dir`, :option:`-m`, :option:`--module` という形式です)。

cmdoption directive is a deprecated alias for the option directive.

.. envvar:: name

現在ドキュメントの対象ととなっているコードやプログラムが使用したり、定義する環境変数について説明します。 envvar というロールを使って参照できます。

.. program:: name

py:currentmodule と同様に、このディレクティブは何も出力しません。その代わりにこのディレクティブを定義すると、Sphinxはこの後に定義される option ディレクティブが説明するオプションが、ここで指定された 名前 を持つプログラムに属するということを認識できるようになります。

program を使用する場合には、 option ロールとプログラム名を適合させる必要があります。以下のような状況について見てみます:

.. program:: rm

.. option:: -r

   Work recursively.

.. program:: svn

.. option:: -r revision

   Specify the revision to work upon.

この場合、 :option:`rm -r` 最初のオプションを示し、 :option:`svn -r` は2番目のオプションを示します。

プログラム名はスペースを含むこともできます。そのため、 svn add や、 svn commit などのサブコマンドを個別に取り扱いたい、というケースにも対応できます。

バージョン 0.5 で追加.

どこのドメインにも属さないような、非常に汎用的なオブジェクトの説明用のディレクティブも存在します:

.. describe:: text
.. object:: text

このディレクティブはドメインで提供されているディレクティブを使ったのと、同じ形式にフォーマットされたテキストを生成します。その代わり、インデックスのエントリーや、クロスリファレンスのターゲットは作成されません:

.. describe:: PAPER

   You can set this variable to select a paper size.

JavaScriptドメイン

JavaScriptドメイン(js)は次のようなディレクティブを提供します:

.. js:function:: name(signature)

JavaScriptの関数やメソッドの説明をします。オプショナルな引数を説明したい場合には、Pythonシグニチャのために 説明したように 角カッコを使用します。

引数や期待される型、関数から投げられるエラー、returnで返される値などのフィールド情報の詳細を書くこともできます:

.. js:function:: $.getJSON(href, callback[, errback])

   :param string href: An URI to the location of the resource.
   :param callback: Gets called with the object.
   :param errback:
       Gets called in case the request fails. And a lot of other
       text so we need multiple lines.
   :throws SomeError: For whatever reason in that case.
   :returns: Something.

次のようにレンダリングされます:

$.getJSON(href, callback[, errback])
引数:
  • href (string) – リソースの場所を示すURI。
  • callback – このオブジェクトのコールバック
  • errback – リクエストが失敗した時のコールバック。また、他のたくさんの文字情報。従って、複数行が必要となります。
例外:

SomeError – その場合のなにかの理由

戻り値:

なにか

.. js:class:: name

オブジェクトを作るコンストラクタの説明をします。基本的には関数と似ていますが、 class という文字が表示されます:

.. js:class:: MyAnimal(name[, age])

   :param string name: The name of the animal
   :param number age: an optional age for the animal

次のようにレンダリングされます:

class MyAnimal(name[, age])
引数:
  • name (string) – 動物の名前
  • age (number) – 動物の年齢。これはオプションです。
.. js:data:: name

グローバル変数や定数の説明です。

.. js:attribute:: object.name

オブジェクト の持つ 属性名 を説明します。

このドメインでは、オブジェクトの説明を参照する、次のようなロールが提供されています:

:js:func:
:js:class:
:js:data:
:js:attr:

reStructuredTextドメイン

reStructuredTextドメイン(rst)は、次のようなディレクティブを提供します:

.. rst:directive:: name

reSTディレクティブの説明をします。 name には単独のディレクティブ名か、引数付きの実際のディレクティブの文法(.. を前に付けたり、後ろに :: を付けたり)で記述をします。例:

.. rst:directive:: foo

   Foo description.

.. rst:directive:: .. bar:: baz

   Bar description.

これは次のようにレンダリングされます

.. foo::

Fooの説明

.. bar:: baz

Barの説明

.. rst:role:: name

reSTのロールの説明をします。 例:

.. rst:role:: foo

   Foo description.

これは次のようにレンダリングされます

:foo:

Fooの説明

このドメインでは、オブジェクトの説明を参照する、次のようなロールが提供されています:

:rst:dir:
:rst:role:

追加のドメイン

sphinx-contrib リポジトリには多くのドメイン拡張が含まれています。現在は Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP, Ruby ドメインがあります。また、Chapel, Common Lisp, dqn, Go, Jinja, Operation, Scala 用のドメインも利用可能です。