Domains

Added in version 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 で説明します。

マークアップの基礎

Most domains provide a number of object description directives, used to describe specific objects provided by modules. Each directive requires one or more signatures to provide basic information about what is being described, and the content should be the description.

A domain will typically keep an internal index of all entities to aid cross-referencing. Typically it will also add entries in the shown general index. If you want to suppress the addition of an entry in the shown index, you can give the directive option flag :no-index-entry:. If you want to exclude the object description from the table of contents, you can give the directive option flag :no-contents-entry:. If you want to typeset an object description, without even making it available for cross-referencing, you can give the directive option flag :no-index: (which implies :no-index-entry:). If you do not want to typeset anything, you can give the directive option flag :no-typesetting:. This can for example be used to create only a target and index entry for later reference. Though, note that not every directive in every domain may support these options.

Added in version 3.2: The directive option noindexentry in the Python, C, C++, and Javascript domains.

Added in version 5.2.3: The directive option :nocontentsentry: in the Python, C, C++, Javascript, and reStructuredText domains.

Added in version 7.2: The directive option no-typesetting in the Python, C, C++, Javascript, and reStructuredText domains.

バージョン 7.2 で変更:

  • The directive option :noindex: was renamed to :no-index:.

  • The directive option :noindexentry: was renamed to :no-index-entry:.

  • The directive option :nocontentsentry: was renamed to :no-contents-entry:.

The previous names are retained as aliases, but will be deprecated and removed in a future version of Sphinx.

An example using a Python domain directive:

.. py:function:: spam(eggs)
                 ham(eggs)

   Spam or ham the foo.

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

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

(This example also shows how to use the :no-index: flag.)

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.

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

The directive option :no-typesetting: can be used to create a target (and index entry) which can later be referenced by the roles provided by the domain. This is particularly useful for literate programming:

.. py:function:: spam(eggs)
   :no-typesetting:

.. code:: python

   def spam(eggs):
       pass

The function :py:func:`spam` does nothing.

デフォルトドメイン

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

.. default-domain:: name

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

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

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

.. function:: pyfunc()

   Describes a Python function.

Reference to :func:`pyfunc`.

クロスリファレンス文法

For cross-reference roles provided by domains, the same cross-referencing modifiers exist as for general cross-references. In short:

  • You may supply an explicit title and reference target: :py:mod:`mathematical functions <math>` will refer to the math module, but the link text will be "mathematical functions".

  • If you prefix the content with an exclamation mark (!), no reference/hyperlink will be created.

  • If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~queue.Queue.get` will refer to queue.Queue.get but only display get as the link text.

Built-in domains

The following domains are included within Sphinx:

追加のドメイン

There are several third-party domains available as extensions, including: