Primer do reStructuredText

reStructuredText é a linguagem de marcação de texto simples usada pelo Sphinx. Esta seção é uma breve introdução aos conceitos e à sintaxe reStructuredText (reST), destinada a fornecer aos autores informações suficientes para criar documentos de forma produtiva. Como o reST foi projetado para ser uma linguagem de marcação simples e discreta, isso não vai demorar muito.

Ver também

A documentação oficial do usuário reStructuredText. Os links “ref” neste documento vinculam à descrição das construções individuais na referência reST.

Parágrafos

O parágrafo (ref) é um documento básico sobre reST. Parágrafos são porções de texto separados por uma ou mais linhas em branco. Como em Python, indentação tem importância em reST, portando todas as linhas do mesmo parágrafo devem estar alinhadas à esquerda para que preservem o mesmo nível de indentação.

Marcação Inline

O padrão reST para marcação inline é simples: use

  • um asterisco: *texto* para enfatizar (itálico),

  • dois asteriscos: **texto** para enfatizar (negrito) e

  • acento grave ou backquotes em inglês: ``texto`` para exemplo de código.

Se asteriscos ou sinais de crase aparecerem no texto corrido e puderem ser confundidos com delimitadores de marcação embutidos, eles deverão ser escapados com uma barra invertida.

Certificar-se de algumas restrições dessas marcações:

  • Não podem ser aninhadas,

  • conteúdo não pode começar nem terminar por espaço em branco: * texto* está incorreto,

  • deve estar separado do texto envolvido por caracteres que não sejam palavras. Utilize sequência barra invertida para contornar: isso é\ *um*\ mundo.

Essas restrições podem ser retiradas em futura versões do docutils.

Também é possível substituir ou expandir algumas dessas marcações inline com funções. Consulte Roles para mais informações.

Listas e Blocos Transcritos

Lista marcada (ref) é natural: apenas colocar um asterisco no início de cada parágrafo e identar apropriadamente. O mesmo acontece para listas numeradas; estas podem ser também autonumeradas usando o sinal #:

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

Listas aninhadas são possíveis, mas cautela pois devem estar separadas das listas hierarquicamente superiores por linhas em branco:

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

Definição listas (ref) são criadas assim:

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

Note que o termo não pode estar em mais de uma linha de texto.

Parágrafos transcritos (ref) são criados apenas indentando-os mais do que os parágrafos do entorno.

Blocos de Linhas (ref) são uma maneira de preservar a quebra das linhas:

| These lines are
| broken exactly like in
| the source file.

Também existem diversos blocos especiais disponíveis:

  • listas de campos (ref, com advertências anotadas em Listas de campos)

  • lista opções (ref)

  • blocos transcrição literal (ref)

  • blocos doctest (ref)

Blocos literais

Blocos código literal (ref) são introduzidos por um final de parágrafo com o marcador especial ::. O bloco literal deve estar indentado e (como todos os parágrafos, separados dos correlatos por uma ou mais linhas em branco):

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

O manuseio do marcador :: é esperto:

  • Se ocorrer em um parágrafo próprio, o parágrafo é ajustado a esquerda do documento.

  • Se for precedido por um espaço em branco, o marcador é removido.

  • Se for precedido por um não-espaço-em-branco o marcador é substituído por uma aspa simples.

Dessa maneira, a segunda sentença no exemplo acima do primeiro parágrafo será renderizado como “O próximo parágrafo é um exemplo de código:”.

O realce de código pode ser ativado para esses blocos literais em toda a documentação, usando a diretiva highlight e em toda a base do projeto, usando a opção de configuração highlight_language. A diretiva code-block pode ser usada para definir o destaque em uma base bloco a bloco. Essas diretrizes são discutidas mais adiante.

Blocos doctest

Blocos de doctest (ref) são sessões Python interativas cortadas e coladas em docstrings. Eles não requerem a sintaxe blocos literais. O bloco doctest deve terminar com uma linha em branco e não deve terminar com um prompt não utilizado:

>>> 1 + 1
2

Tabelas

Para grid tables (ref), você precisa pintar a grade da célula. Eles se parecem com isso:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Simple tables (ref) é mais fácil de gravar, mas limitado: eles devem conter mais de uma linha e as primeiras células da coluna não podem conter várias linhas. Eles se parecem com isso:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

Mais duas sintaxes são suportadas: tabelas CSV e Tabelas de lista. Elas usam um bloco de marcação explícita. Consulte Tabelas para mais informações.

Seções

Seção cabeçalho (ref) são criadas através decomposição (e opcionalmente sobreposição) no título da seção com pontuação de caracter, pelo menos como um texto:

=================
This is a heading
=================

Normalmente, não há níveis de títulos atribuídos a determinados caracteres, pois a estrutura é determinada a partir da sucessão de títulos. No entanto, esta convenção é usada no Guia do desenvolvedor Python para documentação que você pode seguir:

  • # com sublinhado para componentes

  • * com sublinhado para capítulos

  • = para seções

  • - para subseções

  • ^ para subsubseções

  • " para parágrafos

Claro que há liberdade para usar seus próprios caracteres de marcação (veja documentação reST) e use um maior nivel, mas tenha em mente que os formatos alvo (HTML, LaTeX) possuem limites de aninhamento.

Listas de campos

Listas de campos (ref) são seqüências de campos marcados assim:

:fieldname: Field content

Eles são comumente usados em documentação do Python:

def my_function(my_arg, my_other_arg):
    """A function just for me.

    :param my_arg: The first of my arguments.
    :param my_other_arg: The second of my arguments.

    :returns: A message (just for me, of course).
    """

O Sphinx estende o comportamento dos docutils padrão e intercepta as listas de campos especificadas no início dos documentos. Consulte Listas de campos para mais informações.

Roles

Uma role, função, papel ou “custom interpreted text role” (ref) é um pedaço embutido de marcação explícita. Significa que o texto anexo deve ser interpretado de maneira específica. O Sphinx usa isso para fornecer marcação semântica e referência cruzada de identificadores, conforme descrito na seção apropriada. A sintaxe geral é :nomedarole:`conteúdo`.

O Docutils suporta os seguintes roles:

Consulte Roles para funções adicionadas pelo Sphinx.

Marcação Explícita

“Marcação Explicita” (ref é usada em reST para maior parte dos construtores que necessitam de recursos especiais como notas de rodapé, parágrafos destacados, comentários e diretivas gerais.

Um bloco de marcação inicia-se com uma linha com .. seguido por um espaço em branco e terminado pelo próximo parágrafo no mesmo nível de indentação. (Há necessidade de linhas em branco entre marcações explicitas e parágrafos normais. Essa maneira pode parecer complicado, mas é a maneira intuitiva que já usamos para escrever.)

Diretivas

Uma diretiva (ref) é um bloco genérico de marcação explícita. Junto com os roles, é um dos mecanismos de extensão do reST, e o Sphinx faz uso pesado dele.

Docutils suporta as seguintes diretivas:

  • Admonições: attention, caution, danger, error, hint, important, note, tip, warning e a genérica admonition. (A maioria temas estilizam apenas “note” e “warning” especialmente.)

  • Imagens:

  • Elementos adicionais do corpo:

    • contents (um local, ex., para o arquivo autal somente, sumário toc)

    • container (um container com classe configurada, util para gerar separação <div> em HTML)

    • rubric (um cabeçalho sem relação com a seção do documento)

    • topic, sidebar (elementos destadacos especiais no corpo do documento)

    • parsed-literal (bloco literal que suporta marcação inline)

    • epigraph (bloco epigrafado com atribuito opcional de linha)

    • highlights, pull-quote (bloco com seus próprios atributos de classe)

    • compound (parágrafo de composição)

  • Tabelas Especiais

    • table (tabela com título)

    • csv-table (tabela gerada com valores separados por virgulas)

    • list-table (tabela gerada lista de listas)

  • Diretivas Especiais:

    • raw (incluir marcação formato alvo bruto)

    • include (inclui reStructured Text de outro arquivo) – em Sphinx, quando informado o caminho absoluto do arquivo, essa diretiva torna isso relativo ao diretório fonte

    • class (assign a class attribute to the next element)

      Nota

      When the default domain contains a class directive, this directive will be shadowed. Therefore, Sphinx re-exports it as rst-class.

  • Especificidades HTML:

  • Influenciando Markup:

    Desde que haja somente um por arquivo, melhor usar funcionalidades Sphinx para configurar default_role.

Aviso

Não utilize as diretivas sectnum, header nem footer.

As diretivas adicionadas pelo Sphinx são descritas em Diretivas.

Basicamente uma diretiva consiste de um nome, argumentos, opções e conteúdo. (Mantendo esta terminologia em mente, isso será descrito no próximo capítulo descrevendo diretivas personalizadas.) Veja nesse exemplo:

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   Return a line of text input from the user.

função é o nome da diretiva. Isso é obtido com dois argumentos, o restante da primeira linha e a segunda linha, bem como uma opção módulo (como pode ver, opções são dadas em linhas imediatamente consecutivas aos argumentos e indicadas por dois pontos).

O conteúdo da diretiva segue-se após uma linha em branco e com indentação relativa ao início da diretiva ou se as opções estão presentes, pela mesma quantidade que as opções.

Tenha cuidado, pois o recuo não é um número fixo de espaços em branco, por exemplo três, mas qualquer número de espaço em branco. Isso pode ser surpreendente quando um recuo fixo é usado em todo o documento e pode fazer a diferença para diretivas que são sensíveis a espaços em branco. Comparar:

.. code-block::
   :caption: A cool example

       The output of this line starts with four spaces.

.. code-block::

       The output of this line has no spaces at the beginning.

No primeiro bloco de código, o recuo do conteúdo foi fixado pela linha de opção em três espaços, consequentemente o conteúdo começa com quatro espaços. Neste último, o recuo foi fixado pelo próprio conteúdo em sete espaços, portanto, não inicia com um espaço.

Imagens

reST suporta diretiva de imagem (ref), usada assim:

.. image:: gnu.png
   (options)

Quando usado com Sphinx o nome do arquivo (aqui gnu.png) deve ser relativo ao arquivo fonte ou absoluto em relação ao diretório raiz do projeto. Por exemplo, o arquivo sketch/spam.rst refere-se a uma imagem images/spam.png como ../images/spam.png ou /images/spam.png.

Sphinx irá automaticamente copiar o arquivo de imagem para um subdiretório do diretório de construção (ex.: diretório _static para saída HTML.)

Interpretação das opções do tamanho da imagem (largura e altura) é essa: se o tamanho não tem unidade ou a unidade é pixel, então o tamanho suportado será respeitado, para a saída do respectivo canal. Outras unidades como pt (pontos) será usado para saída HTML e LaTeX (pt por bp pois é uma unidade TeX como 72bp=1in).

Sphinx expande os padrões e comportamentos de docutils permitindo extensões:

.. image:: gnu.*

O Sphinx, em seguida, procura todas as imagens que correspondem ao padrão fornecido e determina seu tipo. Cada construtor escolhe a melhor imagem desses candidatos. Por exemplo, se o nome do arquivo gnu.* foi fornecido e dois arquivos gnu.png existiam na árvore de origem, o construtor LaTeX escolheria o antigo, enquanto o construtor HTML preferiria o último. Os tipos de imagem suportados e a prioridade de escolha são definidos em Construtores.

Note que um arquivo com nome de imagem não pode conter espaços.

Alterado na versão 0.4: Adicionado suporte a arquivo com nomes terminados com asterisco.

Alterado na versão 0.6: Imagens podem ter caminho absoluto.

Alterado na versão 1.5: Destino latex suporta pixels (padrão é 96px=1in).

Notas de Rodapé

Para notas rodapé (ref), use [#name]_ para marcar o local da nota de rodapé e adicionar corpo da nota de rodape na base do documento após a rubrica “Footnotes” desse modo:

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

Pode também ser explicitado o número da nota de rodapé ([1]_) ou usar notas de rodapé autonumeradas sem nomes ([#]_).

Citações

Citações padrão em reST (ref) são suportadas, com a funcionalidade adicional que é ser “global”, ou seja, todas citações são referenciadas em todos os arquivos. Use-as assim:

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

Citação é usada de maneira similar ao uso de notas de rodapé, mas com um rótulo que não é numérico nem começa com #.

Substituições

reST suporta “substituições” (ref), os quais são partes do texto ou marcações que se referem ao texto por |name|. São definidos como notas de rodapé com blocos explícitos como esse:

.. |name| replace:: replacement *text*

ou assim:

.. |caution| image:: warning.png
             :alt: Warning!

Veja a referência reST para substituições para detalhes.

If you want to use some substitutions for all documents, put them into rst_prolog or rst_epilog or put them into a separate file and include it into all documents you want to use them in, using the include directive. (Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx finding it as a standalone document.)

Sphinx define algumas substituições padrões, ver Substituições.

Comentários

Cada bloco explícito de marcação que não seja uma construção válida (como notas de rodapé acima) é entendida como um comentário (ref). Por exemplo:

.. This is a comment.

Pode ser indentado texto após um comentário iniciar em um formulário de múltiplos comentários:

..
   This whole indented block
   is a comment.

   Still in the comment.

Metadados de HTML

The meta directive allows specifying the HTML metadata element of a Sphinx documentation page. For example, the directive:

.. meta::
   :description: The Sphinx documentation builder
   :keywords: Sphinx, documentation, builder

vai gerar a seguinte saída HTML:

<meta name="description" content="The Sphinx documentation builder">
<meta name="keywords" content="Sphinx, documentation, builder">

Além disso, o Sphinx adicionará as palavras-chave conforme especificado na diretiva meta ao índice de pesquisa. Assim, o atributo lang do elemento meta é considerado. Por exemplo, a diretiva:

.. meta::
   :keywords: backup
   :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
   :keywords lang=de: bittediesenkeyfinden

adiciona as seguintes palavras aos índices de pesquisa de construções com diferentes configurações do idioma:

  • pleasefindthiskey, pleasefindthiskeytoo para construções em inglês;

  • bittediesenkeyfinden para construções em alemão;

  • backup para construções em todos os idiomas.

Codificação Página

A maneira mais prática de incluir caracteres especiais como barras ou signais de direito autoral em reST é diretamente escrever em caracter Unicode e especificar um código específico. Sphinx assume arquivos fonte estejam em UTF-8 por padrão; o valor pode ser modificado através de source_encoding.

Pegadinhas

Existem algumas pegadinhas que são comuns quando criamos documentos reST:

  • Separação de marcação inline: Como dito, marcações inline devem ser separadas por textos delimitados por caracteres não palavras e deve ser usado barra invertida como escape de espaço. Ver a referência para detalhes.

  • Nenhuma marcação aninhada Algo como *see :func:`foo`* não é possível.