網域¶

在 1.0 版本中新增。

最初，Sphinx 的構想是針對單一專案，即 Python 語言的文件。不久之後，它被開放給所有人作為文件工具使用，但 Python 模組的文件仍然深深地內建於其中 – 最基本的指令，例如 function，是為 Python 物件設計的。由於 Sphinx 已變得相當受歡迎，因此人們對將其用於許多不同的目的產生了興趣：C/C++ 專案、JavaScript，甚至 reStructuredText 標記 (就像本文件一樣)。

雖然這一直以來都是可行的，但現在透過為每個此類目的提供一個網域，可以更輕鬆地支援使用不同程式語言的專案文件，甚至是主要 Sphinx 發行版不支援的語言的文件。

網域是標記 (reStructuredText 指令和角色) 的集合，用於描述和連結到屬於一起的物件，例如程式語言的元素。網域中的指令和角色名稱的格式為 domain:name，例如 py:function。網域也可以提供自訂索引 (例如 Python 模組索引)。

擁有網域意味著當一組文件想要參考例如 C++ 和 Python 類別時，不會有命名問題。這也意味著支援全新語言文件的擴充功能更容易編寫。

本節描述了 Sphinx 包含的網域所提供的內容。網域 API 也記錄在網域 API 節中。

基本標記¶

大多數網域提供許多物件描述指令，用於描述模組提供的特定物件。每個指令都需要一個或多個簽名，以提供有關所描述內容的基本資訊，而內容應為描述。

網域通常會保留所有實體的內部索引，以協助交叉參照。通常，它也會在顯示的一般索引中新增條目。如果您想要抑制在顯示的索引中新增條目，您可以給予指令選項旗標 :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.

這描述了兩個 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.

預設網域

對於僅描述來自一個網域的物件的文件，作者在指定預設網域後，不必在每個指令、角色等中再次聲明其名稱。這可以透過設定值 primary_domain 或透過此指令來完成

.. default-domain:: name¶: 選取新的預設網域。雖然 primary_domain 選取全域預設值，但這僅在同一檔案中有效。

如果未選取其他預設值，則 Python 網域 (名為 py) 是預設網域，主要是為了與為舊版 Sphinx 撰寫的文件相容。

屬於預設網域的指令和角色可以提及，而無需給定網域名稱，即

.. function:: pyfunc()

   Describes a Python function.

Reference to :func:`pyfunc`.

交叉參照語法¶

對於網域提供的交叉參照角色，存在與一般交叉參照相同的交叉參照修飾符。簡而言之

您可以提供明確的標題和參考目標：:py:mod:`mathematical functions <math>` 將參考 math 模組，但連結文字將為 “mathematical functions”。
如果您在內容前面加上驚嘆號 (!)，則不會建立參考/超連結。
如果您在內容前面加上 ~，則連結文字將僅為目標的最後一個元件。例如，:py:meth:`~queue.Queue.get` 將參考 queue.Queue.get，但僅顯示 get 作為連結文字。

內建網域¶

以下網域包含在 Sphinx 中

本頁面中

網域¶

基本標記¶

交叉參照語法¶

內建網域¶

更多網域¶