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ções (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 papéis em um domínio têm nomes como domínio:nome, 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 API de domínio.

Marcação básica¶

A maioria dos domínios fornece uma série de diretivas de descrição de objetos, usadas para descrever objetos específicos fornecidos por módulos. Cada diretiva requer uma ou mais assinaturas para fornecer informações básicas sobre o que está sendo descrito, e o conteúdo deve ser a descrição.

Um domínio normalmente manterá um índice interno de todas as entidades para auxiliar na referência cruzada. Normalmente também vai adicionar entradas no índice geral mostrado. Se você deseja suprimir a adição de uma entrada no índice mostrado, você pode dar à opção de diretiva o sinalizador :no-index-entry:. Se você deseja excluir a descrição do objeto do índice, você pode fornecer o sinalizador de opção da diretiva :no-contents-entry:. Se você deseja compor uma descrição de objeto, sem sequer disponibilizá-la para referência cruzada, você pode dar à opção de diretiva o sinalizador :no-index: (que implica :no-index-entry:) . Se você não deseja compor nada, você pode dar à opção de diretiva o sinalizador :no-typesetting:. Isto pode ser usado, por exemplo, para criar apenas uma entrada de alvo e índice para referência posterior. Porém, observe que nem todas as diretivas em todos os domínios podem oferecer suporte a essas opções.

Adicionado na versão 3.2: A opção de diretiva noindexentry nos domínios Python, C, C++ e Javascript.

Adicionado na versão 5.2.3: A opção de diretiva :nocontentsentry: nos domínios Python, C, C++, Javascript e reStructuredText.

Adicionado na versão 7.2: A opção de diretiva no-typesetting nos domínios Python, C, C++, Javascript e reStructuredText.

Alterado na versão 7.2:

A opção de diretiva :noindex: foi renomeada para :no-index:.
A opção de diretiva :noindexentry: foi renomeada para :no-index-entry:.
A opção de diretiva :nocontentsentry: foi renomeada para :no-contents-entry:.

Os nomes anteriores são mantidos como apelidos, mas serão descontinuados e removidos em uma versão futura do Sphinx.

Um exemplo usando uma diretiva de domínio Python:

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

(Este exemplo também mostra como usar o sinalizador :no-index:.)

Os domínios também fornecem papéis vinculados a essas descrições de objeto. Por exemplo, para vincular a uma das funções descritas no exemplo acima, você poderia dizer

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.

A opção de diretiva :no-typesetting: pode ser usada para criar um alvo (e entrada de índice) que pode posteriormente ser referenciado pelos papéis fornecidos pelo domínio. Isto é particularmente útil para programação alfabetizada:

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

.. code:: python

   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, papel, 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¶

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.

Domínios embutidos¶

Os seguintes domínios estão incluídos no Sphinx:

Mais domínios¶

Existem vários domínios de terceiros disponíveis como extensões, incluindo: