ドメイン¶

バージョン 1.0 で追加。

もともと、Sphinx は Python 言語のドキュメントという単一のプロジェクトのために考案されました。その後まもなく、ドキュメントツールとして誰でも利用できるようになりましたが、Python モジュールのドキュメントは深く組み込まれたままでした。最も基本的なディレクティブである function は、Python オブジェクト向けに設計されていました。Sphinx がある程度普及するにつれて、さまざまな目的 (C/C++ プロジェクト、JavaScript、またはこのドキュメントのように reStructuredText マークアップなど) に使用することに関心が高まりました。

これは常に可能でしたが、現在では、このような目的ごとにドメインを提供することで、異なるプログラミング言語を使用するプロジェクトや、メインの Sphinx ディストリビューションでサポートされていないプロジェクトのドキュメントを簡単にサポートすることがはるかに簡単になりました。

ドメインとは、関連するオブジェクト (プログラミング言語の要素など) を記述し、リンクするためのマークアップ (reStructuredText のディレクティブとロール) のコレクションです。ドメイン内のディレクティブとロールの名前には、domain:name (例: py:function) のような名前が付けられています。ドメインは、カスタムインデックス (Python モジュールインデックスなど) を提供することもできます。

ドメインを持つということは、たとえば、あるドキュメントセットが C++ クラスと Python クラスの両方を参照したい場合に、名前付けの問題が発生しないことを意味します。また、まったく新しい言語のドキュメントをサポートする拡張機能をはるかに簡単に作成できることも意味します。

このセクションでは、Sphinx に含まれているドメインが提供する内容について説明します。ドメイン API については、セクションドメイン API で説明します。

基本マークアップ¶

ほとんどのドメインは、モジュールによって提供される特定のオブジェクトを記述するために使用される、多くのオブジェクト記述ディレクティブを提供します。各ディレクティブは、記述対象に関する基本情報を提供する 1 つ以上のシグネチャを必要とし、内容が説明である必要があります。

ドメインは通常、相互参照を支援するためにすべてのエンティティの内部インデックスを保持します。通常、表示される一般的なインデックスにもエントリを追加します。表示されるインデックスへのエントリの追加を抑制する場合は、ディレクティブオプションフラグ :no-index-entry: を指定できます。目次からオブジェクトの説明を除外する場合は、ディレクティブオプションフラグ :no-contents-entry: を指定できます。相互参照に使用できるようにせずにオブジェクトの説明を組版する場合は、ディレクティブオプションフラグ :no-index: (これは :no-index-entry: を意味します) を指定できます。何も組版したくない場合は、ディレクティブオプションフラグ :no-typesetting: を指定できます。これは、たとえば、後で参照するためのターゲットとインデックスエントリのみを作成するために使用できます。ただし、すべてのドメインのすべてのディレクティブがこれらのオプションをサポートしているわけではないことに注意してください。

バージョン 3.2 で追加: Python、C、C++、および JavaScript ドメインのディレクティブオプション noindexentry。

バージョン 5.2.3 で追加: Python、C、C++、JavaScript、および reStructuredText ドメインのディレクティブオプション :nocontentsentry:。

バージョン 7.2 で追加: Python、C、C++、JavaScript、および reStructuredText ドメインのディレクティブオプション no-typesetting。

バージョン 7.2 で変更

ディレクティブオプション :noindex: が :no-index: に名前変更されました。
ディレクティブオプション :noindexentry: が :no-index-entry: に名前変更されました。
ディレクティブオプション :nocontentsentry: が :no-contents-entry: に名前変更されました。

以前の名前はエイリアスとして保持されますが、Sphinx の将来のバージョンで非推奨になり、削除されます。

Python ドメインディレクティブを使用した例

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

   Spam or ham the foo.

これは、2 つの Python 関数 spam と ham を記述します。(シグネチャが長すぎる場合は、次の行に継続される行にバックスラッシュを追加すると、分割できることに注意してください。例

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

(この例では、:no-index: フラグの使用方法も示しています。)

ドメインは、これらのオブジェクト記述へのリンクを提供するロールも提供します。たとえば、上記の例で説明した関数のいずれかにリンクするには、次のように記述できます。

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

ご覧のとおり、ディレクティブ名とロール名の両方にドメイン名とディレクティブ名が含まれています。

ディレクティブオプション :no-typesetting: を使用して、ドメインによって提供されるロールで後で参照できるターゲット (およびインデックスエントリ) を作成できます。これは、リテラルプログラミングに特に役立ちます。

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

.. code:: python

   def spam(eggs):
       pass

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

デフォルトドメイン

1 つのドメインのオブジェクトのみを記述するドキュメントの場合、デフォルトを指定した後、各ディレクティブ、ロールなどでその名前を再度指定する必要はありません。これは、構成値 primary_domain またはこのディレクティブを使用して行うことができます。

.. default-domain:: name¶: 新しいデフォルトドメインを選択します。primary_domain がグローバルなデフォルトを選択するのに対し、これは同じファイル内でのみ有効です。

他のデフォルトが選択されていない場合、Python ドメイン (名前は py) がデフォルトになります。これは、主に古いバージョンの Sphinx で記述されたドキュメントとの互換性のためのものです。

デフォルトドメインに属するディレクティブとロールは、ドメイン名を指定せずに記述できます。つまり、

.. function:: pyfunc()

   Describes a Python function.

Reference to :func:`pyfunc`.

相互参照の構文¶

ドメインによって提供される相互参照ロールについては、一般的な相互参照と同じ機能が存在します。相互参照の構文を参照してください。

要約すると

明示的なタイトルと参照ターゲットを指定できます: :role:`title <target>` は target を参照しますが、リンクテキストは title になります。
コンテンツの先頭に ! を付けると、参照/ハイパーリンクは作成されません。
コンテンツの先頭に ~ を付けると、リンクテキストはターゲットの最後のコンポーネントのみになります。たとえば、:py:meth:`~Queue.Queue.get` は Queue.Queue.get を参照しますが、リンクテキストとして get のみが表示されます。

組み込みドメイン¶

次のドメインが Sphinx に含まれています

その他のドメイン¶

次の拡張機能として利用可能なサードパーティ製ドメインがいくつかあります。