Referências cruzadas¶

One of Sphinx’s most useful features is creating automatic cross-references through semantic cross-referencing roles. A cross reference to an object description, such as :func:`spam`, will create a link to the place where spam() is documented, appropriate to each output format (HTML, PDF, ePUB, etc.).

Syntax¶

Sphinx supports various cross-referencing roles to create links to other elements in the documentation. In general, writing :role:`target` creates a link to the object called target of the type indicated by role. The link’s text depends the role but is often the same as or similar to target.

The behavior can be modified in the following ways:

Custom link text: You can specify the link text explicitly using the same notation as in reStructuredText external links: :role:`custom text <target>` will refer to target and display custom text as the text of the link.
Suppressed link: Prefixing with an exclamation mark (!) prevents the creation of a link but otherwise keeps the visual output of the role.

For example, writing :py:func:`!target` displays target(), with no link generated.

This is helpful for cases in which the link target does not exist; e.g. changelog entries that describe removed functionality, or third-party libraries that don’t support intersphinx. Suppressing the link prevents warnings in nitpicky mode.
Modified domain reference: When referencing domain objects, a tilde ~ prefix shortens the link text to 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.

Na saída HTML, o atributo título do link (por exemplo, mostrado como uma dica de ferramenta ao passar o mouse) sempre será o nome completo do alvo.

Objetos de referência cruzada¶

Esses papéis são descritos com seus respectivos domínios:

Referência cruzada de locais arbitrários¶

:ref:¶

Para oferecer suporte a referência cruzada para locais arbitrários em qualquer documento, os rótulos reStructuredText padrão são usados. Para que isso funcione, os nomes dos rótulos devem ser exclusivos em toda a documentação. Existem duas maneiras de se referir aos rótulos:

Se você colocar um rótulo diretamente antes do título de uma seção, você pode fazer referência a ele com :ref:`nome-rótulo`. Por exemplo:
```
.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.
```
O papel :ref: geraria então um link para a seção, com o título do link sendo “Section to cross-reference”. Isso funciona tão bem quando a seção e a referência estão em arquivos fontes diferentes.

Rótulos automáticos também funcionam com figuras. Por exemplo:
```
.. _my-figure:

.. figure:: whatever

   Figure caption
```
Neste caso, uma referência :ref:`minha-imagem` iria inserir uma referência à imagem com o texto do link “Legenda da imagem”.

O mesmo funciona para tabelas que recebem uma legenda explícita usando a diretiva table.
Rótulos que não são colocados antes de um título de seção ainda podem ser referenciados, mas você deve dar ao link um título explícito, usando esta sintaxe: :ref:`Título do link <nome-rótulo>`.

Nota

Os rótulos de referência devem começar com um sublinhado. Ao fazer referência a um rótulo, o sublinhado deve ser omitido (veja exemplos acima).

Usar ref é aconselhável em vez de links reStructuredText padrão para seções (como `Título da seção`_) porque funciona em arquivos, quando os títulos das seções são alterados, vai levantar avisos se incorretos e funciona para todos os construtores que oferecem suporte a referências cruzadas.

Fazendo referência cruzada a documentos¶

Adicionado na versão 0.6.

Também existe uma maneira de vincular diretamente aos documentos:

:doc:¶

Link to the specified document; the document name can be a relative or absolute path and is always case-sensitive, even on Windows. For example, if the reference :doc:`parrot` occurs in the document sketches/index, then the link refers to sketches/parrot. If the reference is :doc:`/people` or :doc:`../people`, the link refers to people.

Se nenhum texto de link explícito for fornecido (como de costume: :doc:`Membros do Monty Python </pessoas>`), a legenda do link será o título do documento fornecido.

Fazendo referência a arquivos baixáveis¶

Adicionado na versão 0.6.

:download:¶

Esse papel permite vincular arquivos em sua árvore de fontes que não são documentos reStructuredText que podem ser visualizados, mas arquivos que podem ser baixados.

Quando você usa esse papel, o arquivo referenciado é automaticamente marcado para inclusão na saída durante a construção (obviamente, apenas para saída HTML). Todos os arquivos para download são colocados em um subdiretório _downloads/<hash único>/ do diretório de saída; nomes de arquivos duplicados são tratados.

Um exemplo:

See :download:`this example script <../example.py>`.

O nome de arquivo fornecido geralmente é relativo ao diretório no qual o arquivo fonte atual está contido, mas se for absoluto (começando com /), será considerado relativo ao diretório fonte superior.

O arquivo example.py será copiado para o diretório de saída e um link adequado será gerado para ele.

Para não mostrar links de download indisponíveis, você deve agrupar parágrafos inteiros que tenham este papel:

.. only:: builder_html

   See :download:`this example script <../example.py>`.

Fazendo referência cruzada a figuras por número de figura¶

Adicionado na versão 1.3.

Alterado na versão 1.5: Papel numref também pode fazer referência a seções. E numref permite {name} para o texto do link.

:numref:¶

Link para as figuras, tabelas, blocos de código e seções especificadas; os rótulos reStructuredText padrão são usados. Ao usar este papel, ele irá inserir uma referência à figura com o texto do link pelo número da figura como “Fig. 1.1”.

Se um texto de link explícito for fornecido (como de costume: :numref:`Imagem da Sphinx (Fig. %s) <minha-figura>`), a legenda do link servirá como título da referência. Como espaços reservados, %s e {number} são substituídos pelo número da figura e {name} pela legenda da figura. Se nenhum texto de link explícito for fornecido, a configuração numfig_format é usada como padrão substituto.

Se numfig for False, as figuras não são numeradas, então este papel insere não uma referência, mas o rótulo ou o texto do link.

Fazendo referência cruzada a outros itens de interesse¶

Os seguintes papéis possivelmente criam uma referência cruzada, mas não se referem a objetos:

:confval:¶: Um valor de configuração ou uma definição. Entradas de índice são geradas. Também gera um link para a diretiva confval correspondente, se existir.

:envvar:¶: Uma variável de ambiente. Entradas de índice são geradas. Também gera um link para a diretiva envvar correspondente, se existir.

:token:¶: O nome de um token gramatical (usado para criar links entre as diretivas productionlist).

:keyword:¶: O nome de uma palavra-chave no Python. Isso cria um link para um rótulo de referência com esse nome, se existir.

:option:¶: Uma opção de linha de comando para um programa executável. Isto gera um link para uma diretiva option, se existir.

O papel a seguir cria uma referência cruzada para um termo em um glossário:

:term:¶

Referência a um termo em um glossário. Um glossário é criado usando a diretiva glossary contendo uma lista de definições com termos e definições. Não precisa estar no mesmo arquivo que a marcação term, por exemplo, os documentos do Python têm um glossário global no arquivo glossary.rst.

Se você usar um termo que não esteja explicado em um glossário, receberá um aviso durante a construção.

This role also supports custom link text from the general cross-reference syntax.

Fazendo referência cruzada de qualquer coisa¶

:any:¶

Adicionado na versão 1.3.

Esse papel de conveniência tenta fazer o melhor para localizar um alvo válido para seu texto de referência.

Primeiro, ele tenta alvos de referência cruzada padrão que seriam referenciados por doc, ref ou option.

Objetos personalizados adicionados ao domínio padrão por extensões (veja Sphinx.add_object_type()) também são pesquisados.
Em seguida, ele procura por objetos (alvos) em todos os domínios carregados. Depende dos domínios quão específica deve ser uma correspondência. Por exemplo, no domínio Python uma referência de :any:`Builder` corresponderia à classe sphinx.builders.Builder.

Se nenhum ou vários alvos forem encontrados, um aviso será emitido. No caso de vários alvos, você pode alterar “any” para um papel específico.

Este papel é uma bom candidato para configurar default_role. Se você fizer isso, poderá escrever referências cruzadas sem muita sobrecarga de marcação. Por exemplo, nesta documentação de função Python:

.. function:: install()

   This function installs a `handler` for every signal known by the
   `signal` module.  See the section `about-signals` for more information.

pode haver referências a um termo do glossário (normalmente :term:`handler`), um módulo Python (normalmente :py:mod:`signal` ou :mod:`signal` ) e uma seção (normalmente :ref:`about-signs`).

O papel any também funciona junto com a extensão intersphinx: quando nenhuma referência cruzada local é encontrada, todos os tipos de objetos de inventários intersphinx também são pesquisados.