Domains

バージョン 1.0 で追加.

Sphinxは、もともとある一つのプロジェクトのために考案されたものでした。それはPythonの言語ドキュメンテーションです。程なくして、汎用ドキュメンテーションツールとして提供されるようになりましたが、依然、Pythonモジュールのドキュメンテーションが’深く組み込まれたままで、 function のような最も基本的なディレクティブ群はPythonのオブジェクト用に設計されました。その後、Sphinxがだいぶポピュラーなものになってきたことで、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 domains also provide roles that link back to these object descriptions. For example, to link to one of the functions described in the example above, you could say

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

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

デフォルトドメイン

単一のドメインからなるオブジェクト群を説明するドキュメンテーションでは、デフォルトのドメインを明確にすれば、ディレクティブやロール、その他で都度、何回もそのドメイン名を書く必要はないでしょう。デフォルトのドメインの指定は、primary_domain 値を設定するか、次のディレクティブを使うことでできます:

.. 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 ディレクティブのようなコンテンツを作成することはできません。

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

options

:platform: platforms (comma separated list)

Indicate platforms which the module is available (if it is available on all platforms, the option should be omitted). The keys are short identifiers; examples that are in use include "IRIX", "Mac", "Windows" and "Unix". It is important to use a key which has already been used when applicable.

:synopsis: purpose (text)

Consist of one sentence describing the module's purpose -- it is currently only used in the Global Module Index.

:deprecated: (no argument)

Mark a module as deprecated; it will be designated as such in various locations then.

.. 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ドメインのディレクティブでも同様です)。

options

:async: (no value)

Indicate the function is an async function.

バージョン 2.1 で追加.

.. 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シグニチャ詳細情報フィールドのリスト も参照してください。

options

:abstractmethod: (no value)

Indicate the method is an abstract method.

バージョン 2.1 で追加.

:async: (no value)

Indicate the method is an async method.

バージョン 2.1 で追加.

:classmethod: (no value)

Indicate the method is a class method.

バージョン 2.1 で追加.

:property: (no value)

Indicate the method is a property.

バージョン 2.1 で追加.

:staticmethod: (no value)

Indicate the method is a static method.

バージョン 2.1 で追加.

.. 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() を参照するようになります。

属性名が、現在のクラスのものかどうかを決定するのにも、同様の名前検索の仕組みが使用されます。

Also, if the name is prefixed with a dot, and no exact match is found, the target is taken as a suffix and all object names with that suffix are searched. For example, :py:meth:`.TarFile.close` references the tarfile.TarFile.close() function, even if the current module is not tarfile. Since this can get ambiguous, if there is more than one possible match, you will get a warning from Sphinx.

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

C言語ドメイン

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

.. c:function:: function prototype

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

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

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

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

.. c:member:: declaration

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:: declaration

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

.. c:var:: PyObject* PyClass_Type

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

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

:c:func:

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

:c:member:

Reference a C-language member of a struct.

:c:macro:

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

:c:type:

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

:c:data:

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

C++ドメイン

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

Directives for Declaring Entities

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

.. cpp:class:: class specifier
.. cpp:struct:: class specifier

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

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

The difference between cpp:class and cpp:struct is only cosmetic: the prefix rendered in the output, and the specifier shown in the index.

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

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

A class template can be declared:

.. 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>

バージョン 2.0 で追加: The cpp:struct directive.

.. 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

Describe a (scoped) enum, possibly with the underlying type specified. Any enumerators declared inside an unscoped enum will be declared both in the enum scope and in the parent scope. Examples:

.. 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:union:: name

Describe a union.

バージョン 1.8 で追加.

.. cpp:concept:: template-parameter-list name

警告

The support for concepts is experimental. It is based on the current draft standard and the Concepts Technical Specification. The features may change as they evolve.

Describe a concept. It must have exactly 1 template parameter list. The name may be a nested name. Example:

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

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

   **Notation**

   .. cpp:var:: It r

      An lvalue.

   **Valid Expressions**

   - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
   - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
     :cpp:expr:`r` is incrementable.

This will render as follows:

template<typename It>
concept std::Iterator

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

Notation

It r

An lvalue.

Valid Expressions

  • *r, when r is dereferenceable.

  • ++r, with return type It&, when r is incrementable.

バージョン 1.5 で追加.

オプション

Some directives support options:

  • :noindex:, see マークアップの基礎.

  • :tparam-line-spec:, for templated declarations. If specified, each template parameter will be rendered on a separate line.

    バージョン 1.6 で追加.

Anonymous Entities

C++ supports anonymous namespaces, classes, enums, and unions. For the sake of documentation they must be given some name that starts with @, e.g., @42 or @data. These names can also be used in cross-references and (type) expressions, though nested symbols will be found even when omitted. The @... name will always be rendered as [anonymous] (possibly as a link).

サンプル:

.. cpp:class:: Data

   .. cpp:union:: @data

      .. cpp:var:: int a

      .. cpp:var:: double b

Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.

This will be rendered as:

class Data
union [anonymous]
int a
double b

Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.

バージョン 1.8 で追加.

Aliasing Declarations

Sometimes it may be helpful list declarations elsewhere than their main documentation, e.g., when creating a synopsis of a class interface. The following directive can be used for this purpose.

.. cpp:alias:: name or function signature

Insert one or more alias declarations. Each entity can be specified as they can in the cpp:any role. If the name of a function is given (as opposed to the complete signature), then all overloads of the function will be listed.

例えば:

.. cpp:alias:: Data::a
               overload_example::C::f

becomes

int a
void f(double d) const
void f(double d)
void f(int i)
void f()

whereas:

.. cpp:alias:: void overload_example::C::f(double d) const
               void overload_example::C::f(double d)

becomes

void f(double d) const
void f(double d)

バージョン 2.0 で追加.

Constrained Templates

警告

The support for concepts is experimental. It is based on the current draft standard and the Concepts Technical Specification. The features may change as they evolve.

注釈

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++.

Inline Expressions and Types

:cpp:expr:
:cpp:texpr:

Insert a C++ expression or type either as inline code (cpp:expr) or inline text (cpp:texpr). For example:

.. cpp:var:: int a = 42

.. cpp:function:: int f(int i)

An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).

A type: :cpp:expr:`const MySortedContainer<int>&`
(or as text :cpp:texpr:`const MySortedContainer<int>&`).

will be rendered as follows:

int a = 42
int f(int i)

An expression: a * f(a) (or as text: a * f(a)).

A type: const MySortedContainer<int>& (or as text const MySortedContainer<int>&).

バージョン 1.7 で追加: The cpp:expr role.

バージョン 1.8 で追加: The cpp:texpr role.

名前空間

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 undoes 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 class template std::vector. Equivalently this could have been declared using:

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

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

or:

.. 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.

バージョン 1.4 で追加.

.. 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

バージョン 1.4 で追加.

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

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:struct:
: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.

バージョン 2.0 で追加: The cpp:struct role as alias for the cpp:class role.

Note on References with Templates Parameters/Arguments

These roles follow the Sphinx クロスリファレンス文法 rules. This means care must be taken when referencing a (partial) template specialization, e.g. 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, escape the opening angle bracket with a backslash, like this: :cpp:class:`MyClass\<int>`.

When a custom title is not needed it may be useful to use the roles for inline expressions, cpp:expr and cpp:texpr, where angle brackets do not need escaping.

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.

Overloaded (member) functions

When a (member) function is referenced using just its name, the reference will point to an arbitrary matching overload. The cpp:any and cpp:func roles use an alternative format, which simply is a complete function declaration. This will resolve to the exact matching overload. As example, consider the following class declaration:

class C
void f(double d) const
void f(double d)
void f(int i)
void f()

References using the cpp:func role:

Note that the add_function_parentheses configuration variable does not influence specific overload references.

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 parameter declarations, and template arguments for the prefix of qualified names. For example:

  • template\<typename TOuter> Wrapper::Outer (template<typename TOuter> Wrapper::Outer)

  • template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner (template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner)

Currently the lookup only succeed if the template parameter identifiers are equal strings. That is, template\<typename UOuter> Wrapper::Outer will not work.

As a shorthand notation, if a template parameter list is omitted, then the lookup will assume either a primary template or a non-template, but not a partial template specialisation. This means the following references work as well:

(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.

The directive will create cross-reference targets for the given options, referenceable by option (in the example case, you'd use something like :option:`dest_dir`, :option:`-m`, or :option:`--module`).

cmdoption directive is a deprecated alias for the option directive.

.. envvar:: name

Describes an environment variable that the documented code or program uses or defines. Referenceable by 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:module:: name

This directive sets the module name for object declarations that follow after. The module name is used in the global module index and in cross references. This directive does not create an object heading like py:class would, for example.

By default, this directive will create a linkable entity and will cause an entry in the global module index, unless the noindex option is specified. If this option is specified, the directive will only update the current module name.

バージョン 1.6 で追加.

.. 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:method:: name(signature)

This directive is an alias for js:function, however it describes a function that is implemented as a method on a class object.

バージョン 1.6 で追加.

.. 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:mod:
:js:func:
:js:meth:
: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:directive:option:: name

Describes an option for reST directive. The name can be a single option name or option name with arguments which separated with colon (:). For example:

.. rst:directive:: toctree

   .. rst:directive:option:: caption: caption of ToC

   .. rst:directive:option:: glob

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

.. toctree::
:caption: caption of ToC
:glob:

options

:type: description of argument (text)

Describe the type of option value.

例えば:

.. rst:directive:: toctree

   .. rst:directive:option:: maxdepth
      :type: integer or no value

バージョン 2.1 で追加.

.. rst:role:: name

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

.. rst:role:: foo

   Foo description.

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

:foo:

Fooの説明

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

:rst:dir:
:rst:role:

The Math Domain

The math domain (name math) provides the following roles:

.. rst:role:: math:numref

Role for cross-referencing equations defined by math directive via their label. Example:

.. math:: e^{i\pi} + 1 = 0
   :label: euler

Euler's identity, equation :math:numref:`euler`, was elected one of the
most beautiful mathematical formulas.

バージョン 1.8 で追加.

追加のドメイン

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