Papéis

O Sphinx usa papéis (roles, em inglês) de texto interpretado para inserir marcação semântica em documentos. Eles são escritos como :nomedopapel:`conteúdo.

Nota

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

Veja Domínios para papéis adicionados por domínios.

Referências cruzadas

Veja Referências cruzadas.

Papéis de referência cruzada incluem:

Realce de código em linha

:code:

Um exemplo de código em linha, ou inline. Quando usado diretamente, este papel apenas exibe o texto sem realce de sintaxe, como um literal.

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

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

Ao contrário da diretiva code-block, este papel não respeita a linguagem padrão definida pela diretiva highlight.

Para ativar o realce de sintaxe, você deve primeiro usar a diretiva role do Docutils para definir um papel personalizado associado a uma linguagem específico:

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

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

Para exibir um exemplo de código multilinha, use a diretiva code-block.

Mathemática

:math:

Papel para operações matemáticas em linha. Use assim:

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

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

:eq:

Mesmo que math:numref.

Outras marcações semânticas

Os papéis a seguir não fazem nada de especial, exceto formatar o texto em um estilo diferente:

:abbr:

Uma abreviação. Se o conteúdo do papel contiver uma explicação entre parênteses, ele será tratado de maneira especial: será mostrado em uma dica de ferramenta em HTML e exibido apenas uma vez em LaTeX.

Por exemplo: :abbr:`LIFO (last-in, first-out)` exibe LIFO.

Adicionado na versão 0.6.

:command:

O nome de um comando no nível do sistema operacional, como rm.

Por exemplo: rm

:dfn:

Marca a instância definidora de um termo no texto. (Nenhuma entrada de índice é gerada.)

Por exemplo: binary mode

:file:

O nome de um arquivo ou diretório. Dentro do conteúdo, você pode usar chaves para indicar uma parte “variável”, por exemplo:

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

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

Na documentação construída, o x será exibido de forma diferente para indicar que será substituído pela versão secundária do Python.

:guilabel:

Rótulos apresentados como parte de uma interface de usuário interativa devem ser marcados usando guilabel. Isto inclui rótulos de interfaces baseadas em texto, como aquelas criadas usando curses ou outras bibliotecas baseadas em texto. Qualquer rótulo usado na interface deve ser marcado com este papel, incluindo rótulos de botões, títulos de janelas, nomes de campos, nomes de menus e seleções de menu e até mesmo valores em listas de seleção.

Alterado na versão 1.0: Uma chave aceleradora para o rótulo da GUI pode ser incluída usando um E comercial; isso será removido e exibido sublinhado na saída (por exemplo: :guilabel:`&Cancel` exibe Cancel). Para incluir um E comercial literal, duplique-o.

:kbd:

Marca uma sequência de teclas. A forma que a sequência de teclas assume pode depender das convenções específicas da plataforma ou da aplicação. Quando não há convenções relevantes, os nomes das teclas modificadoras devem ser explicitados, para melhorar a acessibilidade para novos usuários e falantes não nativos. Por exemplo, uma sequência de teclas xemacs pode ser marcada como :kbd:`C-x C-f`, mas sem referência a uma aplicação ou plataforma específica, a mesma sequência deve ser marcada como :kbd:`Control- x Control-f`, exibindo C-x C-f e Control-x Control-f respectivamente.

:mailheader:

O nome de um cabeçalho de correio estilo RFC 822. Essa marcação não implica que o cabeçalho esteja sendo usado em uma mensagem de e-mail, mas pode ser usada para se referir a qualquer cabeçalho do mesmo “estilo”. Isso também é usado para cabeçalhos definidos pelas diversas especificações MIME. O nome do cabeçalho deve ser inserido da mesma forma que normalmente seria encontrado na prática, sendo preferidas as convenções de tripa de camelo quando houver mais de um uso comum. Por exemplo: :mailheader:`Content-Type` exibe Content-Type.

:makevar:

O nome de uma variável make.

Por exemplo: help

:manpage:

Uma referência a uma página man do Unix incluindo a seção, por exemplo, :manpage:`ls(1)` exibe ls(1). Cria um hiperlink para um site externo que renderiza a página man se manpages_url estiver definido.

Alterado na versão 7.3: Permite especificar um alvo com <>, como hiperlinks. Por exemplo, :manpage:`blah <ls(1)>` exibe blah.

:menuselection:

As seleções de menu devem ser marcadas usando o papel menuselection. Isto é usado para marcar uma sequência completa de seleções de menu, incluindo a seleção de submenus e a escolha de uma operação específica ou qualquer subsequência de tal sequência. Os nomes das seleções individuais devem ser separados por -->.

Por exemplo, para marcar a seleção “Start > Programs”, use esta marcação:

:menuselection:`Start --> Programs`

Exibe: Start ‣ Programs

Ao incluir uma seleção que inclui algum indicador ao final, como as reticências que alguns sistemas operacionais usam para indicar que o comando abre uma caixa de diálogo, o indicador deve ser omitido do nome da seleção.

menuselection também têm suporte a aceleradores com E comercial, assim como guilabel.

:mimetype:

O nome de um tipo MIME ou de um componente de um tipo MIME (a parte maior ou menor, isoladamente).

Por exemplo: text/plain

:newsgroup:

O nome de um grupo de notícias da Usenet.

Por exemplo: comp.lang.python

:program:

O nome de um programa executável. Isso pode ser diferente do nome do arquivo executável em algumas plataformas. Em particular, a extensão .exe (ou outra) deve ser omitida para programas Windows.

Por exemplo: curl

:regexp:

Uma expressão regular. Aspas não devem ser incluídas.

Por exemplo: ([abc])+

:samp:

Um pedaço de texto literal, como código. Dentro do conteúdo, você pode usar chaves para indicar uma parte “variável”, como em file. Por exemplo, em :samp:`print(1+{variable})`, a parte variable seria enfatizada: print(1+variable)

Se você não precisa da indicação “parte variável”, use o papel padrão code.

Alterado na versão 1.8: É permitido escapar chaves com barra invertida dupla. Por exemplo, em :samp:`print(f"answer=\\{1+{variable}*2\\}")`, a parte variable seria enfatizada e as chaves de escape seria exibido: print(f"answer={1+variable*2}")

Há também um papel index para gerar entradas de índice.

Os seguintes papéis geram links externos:

:cve:

Uma referência a um registro Common Vulnerabilities and Exposures. Isso gera entradas de índice apropriadas. O texto “CVE número“ é gerado; com um link para uma cópia online do CVE especificado. Você pode criar um link para uma seção específica usando :cve:`número#âncora`.

Por exemplo: CVE 2020-10735

Adicionado na versão 8.1.

:cwe:

Uma referência a uma Common Weakness Enumeration. Isso gera entradas de índice apropriadas. O texto “CWE número“ é gerado; na saída HTML, com um link para uma cópia online do CWE especificado. Você pode criar um link para uma seção específica usando :cwe:`número#âncora`.

Por exemplo: CWE 787

Adicionado na versão 8.1.

:pep:

Uma referência a uma Python Enhancement Proposal (Proposta de Melhoria do Python, em uma tradução livre). Isso gera entradas de índice apropriadas. O texto “PEP número" é gerado; na saída HTML, este texto é um hiperlink para uma cópia online da PEP especificada. Você pode vincular a uma seção específica dizendo :pep:`número#âncora`.

Por exemplo: PEP 8

:rfc:

Uma referência a um Internet Request for Comments (Pedido de Comentários, em uma tradução livre). Isso gera entradas de índice apropriadas. O texto “RFC número" é gerado; na saída HTML, este texto é um hiperlink para uma cópia online do RFC especificado. Você pode vincular a uma seção específica dizendo :rfc:`número#âncora`.

Por exemplo: RFC 2324

Observe que não há papéis especiais para incluir hiperlinks, pois você pode usar a marcação reStructuredText padrão para essa finalidade.

Substituições

O sistema de documentação fornece algumas substituições definidas por padrão. Eles são definidos no arquivo de configuração de construção.

|release|

Substituído pela versão do projeto à qual a documentação se refere. Esta deve ser a string da versão completa, incluindo tags alfa/beta/candidatas a lançamento, por exemplo. 2.5.2b3. Definido por release.

|version|

Substituído pela versão do projeto à qual a documentação se refere. Isto deve consistir apenas nas partes da versão principal e secundária, por ex. 2.5, mesmo para a versão 2.5.1. Definido por version.

|today|

Substituído pela data de hoje (a data em que o documento é lido) ou pela data definida no arquivo de configuração de construção. Normalmente tem o formato April 14, 2007. Definido por today_fmt e today.

|translation progress|

Substituído pelo andamento da tradução do documento. Esta substituição destina-se a ser usada por tradutores de documentos como um marcador para o progresso da tradução do documento.