Primer do reStructuredText

Essa seção é uma breve introdução aos conceitos e sintaxe do (reST) reStructuredText, necessária para fornecer aos autores documentação mínima e produtiva. O reSt foi desenhado para ser uma linguagem marcada, simples e eficaz e isso não faz muito tempo.

Ver também

A documentação original está em Documentação para Usuário do reStructuredText. Todos os links “ref” utilizam este documento para descrever referências a construções 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 correlado.

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
  • aspas backquotes <shift+crase> em pt-BR: ``texto`` para exemplo de código.

Se asteriscos ou <shift-aspas> `` `` aparecem no texto e confundem-se com o texto utilizar backslash (barra invertida) como escape.

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.

reST também permite configurar “regras de interpretação de texto”, as quais significam que texto delimitados devem ser interpretados de uma maneira específica. Sphinx usa isso para prover marcação semântica e referência cruzada de identificadores, como descrito na seção apropriada. Em geral a sintaxe é: :nome-regra:`conteúdo`.

O reST padrão provê as seguintes regras / roles:

  • emphasis – alternativa para escrever *emphasis*
  • strong – alternativa para escrever **strong**
  • literal – alternativa para escrever ``literal``
  • subscript – texto subscritor
  • superscript – texto escrita superior
  • title-reference – para títulos de livros, periódicos e outros materiais

Ver Marcação Inline para regras adicionadas pelo Sphinx.

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:

  • lista campos (ref)
  • lista opções (ref)
  • blocos transcrição literal (ref)
  • blocos doctest (ref)

Código Fonte

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

Tabelas

Duas formas para tabelas são suportadas. Para grid tables (ref) “construir” o conjunto. Parecer 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             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Tabelas Simples (ref) are easier to write, but limited: they must contain more than one row, and the first column cannot contain multiple lines. They look like this:

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

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
=================

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this convention is used in Python’s Style Guide for documenting which you may follow:

  • # com overline 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.

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

A diretiva (ref) é um bloco genérico de marcação explícita. Apesar da abrangência, é um dos mecanismos de extensão do reST e Sphinx faz uso intensivo dela.

Docutils suporta as seguintes diretivas:

  • Admonitions: attention, caution, danger, error, hint, important, note, tip, warning e geral admonition. (Muitos stilos de themas só “note” e “warning” especialmente.)

  • Imagens:

    • image (ver também Images abaixo)
    • figure (uma imagem com legenda e legenda opcional)
  • Elementos Adicionais corpo:

    • conteúdos (um local, ex. para o arquivo corrente, 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 (assinala atributo a uma classe para o próximo elemento) [1]
  • Especificidades HTML:

    • meta (geração de HTML <meta> tags)
    • title (sobrepõe título do documento)
  • Influenciando Markup:

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

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

Diretivas adicionadas pelo Sphinx são descritas em Construtores Marcados Sphinx.

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.

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.*

Quando Sphinx busca todas imagens que combinam com o padrão sugerido e determina seu tipo. Cada construtor escolhe a melhor imagem candidata. Por exemplo, se o nome gnu.* é informado e dois arquivos gnu.pdf and gnu.png existem na raiz de diretórios fonte, o construtor LaTeX irá escolher primeiro e o HTML irá escolherr o último. Tipos de imagem e prioridade de escolha são definidos nos Construtores disponíveis.

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”, ex.. 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*

or assim:

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

Ver reST para referências a detalhes em substituições.

Se for usar alguma substituição para todos os documentos, colocar em rst_prolog ou colocar em arquivos separados e incluir em todos os documentos desejados, onde for usado, usando diretiva include. (Certificar-se de atribuir ao arquivo uma extensão diferente daquela usada como fonte de arquivos Sphinx, para evitar que o Sphinx interprete como um documento independente).

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.

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 the reference para detalhes.
  • Nenhuma marcação aninhada Algo como *see :func:`foo`* não é possível.

Notas de Rodapé

[1]Quando um domínio padrão contém diretiva classe class, essa diretiva será ocultada, entretanto, Sphinx irá reexportá-la como rst-class.