Domínios

Adicionado na versão 1.0.

Originalmente, o Sphinx foi concebido para um único projeto, a documentação da linguagem Python. Pouco depois, foi disponibilizado para todos como uma ferramenta de documentação, mas a documentação dos módulos Python permaneceu profundamente embutida – as diretivas mais fundamentais, como function, foram projetadas para objetos Python. Como o Sphinx se tornou um tanto popular, surgiu o interesse em usá-lo para muitos propósitos diferentes: projetos C/C++, JavaScript ou mesmo marcação reStructuredText (como nesta documentação).

Enquanto isso sempre foi possível, agora é muito mais fácil apoiar facilmente a documentação de projetos usando linguagens de programação diferentes ou mesmo aquelas não suportadas pela distribuição principal do Sphinx, fornecendo um domínio para cada uma dessas finalidades.

Um domínio é uma coleção de marcação (diretivas e papéis do reStructuredText) para descrever e vincular a objetos pertencentes um ao outro, por exemplo, elementos de uma linguagem de programação. Nomes de diretivas e papeis em um domínio têm nomes como domain:name, por exemplo py:function. Os domínios também podem fornecer índices personalizados (como o índice do módulo Python).

Ter domínios significa que não há problemas de nomenclatura quando um conjunto de documentação deseja fazer referência a, por exemplo, classes C++ e Python. Isso também significa que as extensões que têm suporte a documentação de novas linguagens são muito mais fáceis de serem escritas.

Esta seção descreve o que os domínios incluídos no Sphinx fornecem. A API de domínio também está documentada na seção Domain API.

Marcação Básica

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.

Adicionado na versão 3.2: The directive option noindexentry in the Python, C, C++, and Javascript domains.

Adicionado na versão 5.2.3: The directive option :nocontentsentry: in the Python, C, C++, Javascript, and reStructuredText domains.

Adicionado na versão 7.2: The directive option no-typesetting in the Python, C, C++, Javascript, and reStructuredText domains.

Alterado na versão 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.

Isso descreve as duas funções Python spam e ham. (Observe que quando as assinaturas ficam muito longas, você pode quebrá-las se adicionar uma barra invertida às linhas que continuam na próxima linha. Exemplo:

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

Como você pode ver, os nomes de diretiva e papel contêm o nome de domínio e o nome da diretiva.

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

   def spam(eggs):
       pass

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

Domínio Padrão

Para documentação que descreve objetos de apenas um domínio, os autores não terão que declarar novamente seu nome em cada diretiva, função, etc… depois de especificar um padrão. Isso pode ser feito por meio do valor de configuração primary_domain ou por meio desta diretiva:

.. default-domain:: name

Selecione um novo domínio padrão. Enquanto primary_domain seleciona um padrão global, isso só tem efeito dentro do mesmo arquivo.

Se nenhum outro padrão for selecionado, o domínio Python (denominado py) é o padrão, principalmente para compatibilidade com a documentação escrita para versões anteriores do Sphinx.

As diretivas e papéis que pertencem ao domínio padrão podem ser mencionadas sem fornecer o nome do domínio, ou seja:

.. function:: pyfunc()

   Describes a Python function.

Reference to :func:`pyfunc`.

Sintaxe de referência cruzada

Para papéis de referência cruzada fornecidas por domínios, existem os mesmos recursos que existem para referências cruzadas gerais. Veja Sintaxe de referência cruzada.

Resumindo:

  • Você pode fornecer um título explícito e destino de referência: :role:`title <target>` irá se referir a target, mas o texto do link será title.

  • Se você prefixar o conteúdo com !, nenhuma referência/hiperlink será criada.

  • Se você prefixar o conteúdo com ~, o texto do link será apenas o último componente do destino. Por exemplo, :py:meth:`~Queue.Queue.get` irá se referir a Queue.Queue.get, mas somente exibirá get como o texto do link.

Built-in domains

The following domains are included within Sphinx:

More domains

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