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) eacento 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.
Hiperlinks¶
Links externos¶
Use `Texto do link <https://domínio.inválido/>`_
para links da Web embutidos. Se o texto do link deve ser o endereço da web, você não precisa de nenhuma marcação especial, o analisador encontra links e endereços de e-mail em texto comum.
Importante
Deve haver um espaço enter o texto do link da URL e o < de abertura.
Também é possível separar o link da definição do alvo (ref) como isso:
This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/
Links internos¶
Ligações internas são feitas através de regra reST provida por Sphinx, ver seção na marcação específica Referência cruzada de locais arbitrários.
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:
emphasis – equivalente a
*emphasis*
strong – equivalente a
**strong**
literal – equivalente a
``literal``
subscript – texto escrita inferior
superscript – texto escrita superior
title-reference – para títulos de livros, periódicos e outros materiais
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 asrst-class
.
Especificidades HTML:
meta (geração de tags
<meta>
HTML, veja também Metadados de HTML abaixo)title (sobrepõe título do documento)
Influenciando Markup:
default-role (define nova role padrão)
role (cria nova role)
Desde que haja somente um por arquivo, melhor usar funcionalidades Sphinx para configurar
default_role
.
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.
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.
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: