Roles

O Sphinx usa roles de texto interpretado para inserir marcação semântica em documentos. Eles são escritos como :nome_da_role:`conteúdo`.

Nota

A role padrão (`conteúdo`) não tem nenhum significado especial por padrão. Você é livre para usá-la para o que quiser, por exemplo, nomes de variáveis; use o valor de configuração default_role para defini-lo para uma role conhecido – a role any para encontrar qualquer coisa ou a role py:obj para encontrar objetos Python são muito útil para isso.

Veja Domínios para roles adicionadas por domínios.

Sintaxe de referência cruzada

As referências cruzadas são geradas por muitas roles de texto interpretado semântico. Basicamente, você só precisa escrever :role:`destino`, e um link será criado para o item chamado destino do tipo indicado por role. O texto do link será o mesmo que destino.

Existem alguns recursos adicionais, no entanto, que tornam as roles de referência cruzada mais versáteis:

  • Você pode fornecer um título explícito e destino de referência, como nos hiperlinks reST diretos: :role:`título <destino>` vai fazer referência a destino, mas o texto do link será título.

  • 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` vai fazer referência a Queue.Queue.get, mas somente exibirá get como o texto do link. Isso não funciona com todas as funções de referência cruzada, mas é específico do domínio.

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

Fazendo referência cruzada de qualquer coisa

:any:

Novo na versão 1.3.

Essa role de conveniência tenta fazer o melhor para localizar um destino válido para seu texto de referência.

  • Primeiro, ele tenta destinos 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 (destinos) 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 destinos forem encontrados, um aviso será emitido. No caso de vários destinos, você pode alterar “any” para uma role específica.

This role is a good candidate for setting default_role. If you do, you can write cross-references without a lot of markup overhead. For example, in this Python function documentation:

.. 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:`texto`), um módulo Python (normalmente :py:mod:`signal` ou :mod:`signal` ) e uma seção (normalmente :ref:`about-signs`).

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

Objetos de referência cruzada

Essas roles são descritas 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 reST 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`.

    A role ``:ref: `` geraria então um link para a seção, com o título do link sendo “Seção para referência cruzada”. Isso funciona tão bem quando a seção e a referência estão em arquivos fontes diferentes.

    Etiquetas automáticas 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

Reference labels must start with an underscore. When referencing a label, the underscore must be omitted (see examples above).

Using ref is advised over standard reStructuredText links to sections (like `Section title`_) because it works across files, when section headings are changed, will raise warnings if incorrect, and works for all builders that support cross-references.

Cross-referencing documents

Novo na versão 0.6.

There is also a way to directly link to documents:

:doc:

Link to the specified document; the document name can be specified in absolute or relative fashion. 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.

If no explicit link text is given (like usual: :doc:`Monty Python members </people>`), the link caption will be the title of the given document.

Referencing downloadable files

Novo na versão 0.6.

:download:

This role lets you link to files within your source tree that are not reST documents that can be viewed, but files that can be downloaded.

When you use this role, the referenced file is automatically marked for inclusion in the output when building (obviously, for HTML output only). All downloadable files are put into a _downloads/<unique hash>/ subdirectory of the output directory; duplicate filenames are handled.

An example:

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

The given filename is usually relative to the directory the current source file is contained in, but if it absolute (starting with /), it is taken as relative to the top source directory.

The example.py file will be copied to the output directory, and a suitable link generated to it.

Not to show unavailable download links, you should wrap whole paragraphs that have this role:

.. only:: builder_html

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

Cross-referencing figures by figure number

Novo na versão 1.3.

Alterado na versão 1.5: numref role can also refer sections. And numref allows {name} for the link text.

:numref:

Link to the specified figures, tables, code-blocks and sections; the standard reST labels are used. When you use this role, it will insert a reference to the figure with link text by its figure number like “Fig. 1.1”.

If an explicit link text is given (as usual: :numref:`Image of Sphinx (Fig. %s) <my-figure>`), the link caption will serve as title of the reference. As placeholders, %s and {number} get replaced by the figure number and {name} by the figure caption. If no explicit link text is given, the numfig_format setting is used as fall-back default.

If numfig is False, figures are not numbered, so this role inserts not a reference but the label or the link text.

Cross-referencing other items of interest

The following roles do possibly create a cross-reference, but do not refer to objects:

:envvar:

An environment variable. Index entries are generated. Also generates a link to the matching envvar directive, if it exists.

:token:

The name of a grammar token (used to create links between productionlist directives).

:keyword:

The name of a keyword in Python. This creates a link to a reference label with that name, if it exists.

:option:

A command-line option to an executable program. This generates a link to a option directive, if it exists.

The following role creates a cross-reference to a term in a glossary:

:term:

Reference to a term in a glossary. A glossary is created using the glossary directive containing a definition list with terms and definitions. It does not have to be in the same file as the term markup, for example the Python docs have one global glossary in the glossary.rst file.

If you use a term that’s not explained in a glossary, you’ll get a warning during build.

Inline code highlighting

:code:

An inline code example. When used directly, this role just displays the text without syntax highlighting, as a literal.

By default, inline code such as :code:`1 + 2` just displays without
highlighting.

Displays: By default, inline code such as 1 + 2 just displays without highlighting.

Unlike the code-block directive, this role does not respect the default language set by the highlight directive.

To enable syntax highlighting, you must first use the Docutils role directive to define a custom role associated with a specific language:

.. role:: python(code)
   :language: python

In Python, :python:`1 + 2` is equal to :python:`3`.

To display a multi-line code example, use the code-block directive instead.

Math

:math:

Role para math inline. Use assim:

Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.

Displays: Since Pythagoras, we know that \(a^2 + b^2 = c^2\).

:eq:

Same as math:numref.

Other semantic markup

The following roles don’t do anything special except formatting the text in a different style:

:abbr:

An abbreviation. If the role content contains a parenthesized explanation, it will be treated specially: it will be shown in a tool-tip in HTML, and output only once in LaTeX.

For example: :abbr:`LIFO (last-in, first-out)` displays LIFO.

Novo na versão 0.6.

:command:

The name of an OS-level command, such as rm.

For example: rm

:dfn:

Mark the defining instance of a term in the text. (No index entries are generated.)

For example: binary mode

:file:

The name of a file or directory. Within the contents, you can use curly braces to indicate a “variable” part, for example:

... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...

Displays: … is installed in /usr/lib/python3.x/site-packages …

In the built documentation, the x will be displayed differently to indicate that it is to be replaced by the Python minor version.

:guilabel:

Labels presented as part of an interactive user interface should be marked using guilabel. This includes labels from text-based interfaces such as those created using curses or other text-based libraries. Any label used in the interface should be marked with this role, including button labels, window titles, field names, menu and menu selection names, and even values in selection lists.

Alterado na versão 1.0: An accelerator key for the GUI label can be included using an ampersand; this will be stripped and displayed underlined in the output (for example: :guilabel:`&Cancel` displays Cancel). To include a literal ampersand, double it.

:kbd:

Mark a sequence of keystrokes. What form the key sequence takes may depend on platform- or application-specific conventions. When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers. For example, an xemacs key sequence may be marked like :kbd:`C-x C-f`, but without reference to a specific application or platform, the same sequence should be marked as :kbd:`Control-x Control-f`, displaying C-x C-f and Control-x Control-f respectively.

:mailheader:

The name of an RFC 822-style mail header. This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same “style.” This is also used for headers defined by the various MIME specifications. The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage. For example: :mailheader:`Content-Type` displays Content-Type.

:makevar:

The name of a make variable.

For example: help

:manpage:

A reference to a Unix manual page including the section, e.g. :manpage:`ls(1)` displays ls(1). Creates a hyperlink to an external site rendering the manpage if :confval:`manpages_url is defined.

:menuselection:

Menu selections should be marked using the menuselection role. This is used to mark a complete sequence of menu selections, including selecting submenus and choosing a specific operation, or any subsequence of such a sequence. The names of individual selections should be separated by -->.

For example, to mark the selection “Start > Programs”, use this markup:

:menuselection:`Start --> Programs`

Displays: Start ‣ Programs

When including a selection that includes some trailing indicator, such as the ellipsis some operating systems use to indicate that the command opens a dialog, the indicator should be omitted from the selection name.

menuselection also supports ampersand accelerators just like guilabel.

:mimetype:

The name of a MIME type, or a component of a MIME type (the major or minor portion, taken alone).

For example: text/plain

:newsgroup:

The name of a Usenet newsgroup.

For example: comp.lang.python

Por fazer

Is this not part of the standard domain?

:program:

The name of an executable program. This may differ from the file name for the executable for some platforms. In particular, the .exe (or other) extension should be omitted for Windows programs.

For example: curl

:regexp:

A regular expression. Quotes should not be included.

For example: ([abc])+

:samp:

A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a “variable” part, as in file. For example, in :samp:`print 1+{variable}`, the part variable would be emphasized: print 1+variable

If you don’t need the “variable part” indication, use the standard code role instead.

Alterado na versão 1.8: Allowed to escape curly braces with backslash

There is also an index role to generate index entries.

The following roles generate external links:

:pep:

A reference to a Python Enhancement Proposal. This generates appropriate index entries. The text “PEP number“ is generated; in the HTML output, this text is a hyperlink to an online copy of the specified PEP. You can link to a specific section by saying :pep:`number#anchor`.

For example: PEP 8

:rfc:

A reference to an Internet Request for Comments. This generates appropriate index entries. The text “RFC number“ is generated; in the HTML output, this text is a hyperlink to an online copy of the specified RFC. You can link to a specific section by saying :rfc:`number#anchor`.

For example: RFC 2324

Note that there are no special roles for including hyperlinks as you can use the standard reST markup for that purpose.

Substituições

The documentation system provides three substitutions that are defined by default. They are set in the build configuration file.

|release|

Replaced by the project release the documentation refers to. This is meant to be the full version string including alpha/beta/release candidate tags, e.g. 2.5.2b3. Set by release.

|version|

Replaced by the project version the documentation refers to. This is meant to consist only of the major and minor version parts, e.g. 2.5, even for version 2.5.1. Set by version.

|today|

Replaced by either today’s date (the date on which the document is read), or the date set in the build configuration file. Normally has the format April 14, 2007. Set by today_fmt and today.