Diretivas¶
Como discutido anteriormente, uma diretiva é um bloco genérico de marcação explícita. Enquanto o Docutils fornece várias diretivas, o Sphinx fornece muito mais e usa diretivas como um dos mecanismos de extensão primários.
Veja Domínios para papéis adicionados por domínios.
Ver também
Confira o Primer de reStructuredText para uma visão geral das diretivas fornecidas pelo Docutils.
Tabela de conteúdo¶
Como reStructuredText não tem funcionalidades para conectar diversos documentos ou dividir documentos em múltiplos arquivos de saída, Sphinx usa uma diretiva configurada para adicionar relações entre arquivos simples da documentação criada e de tabelas de conteúdos. A diretiva toctree
é um elemento central.
Nota
A simples “inclusão” de um arquivo em outro pode ser feita com a diretiva include.
Nota
Para criar um índice para o documento atual (arquivo .rst), use o padrão reStructuredText diretiva de conteúdo.
- .. toctree::¶
Esta diretiva insere uma “árvore TOC” na localização atual, usando os TOCs individuais (incluindo “árvores subTOC”) dos documentos fornecidos no corpo da diretiva. Os nomes de documentos relativos (não começando com uma barra) são relativos ao documento em que a diretiva ocorre, os nomes absolutos são relativos ao diretório fonte. Uma opção numérica
maxdepth
pode ser fornecida para indicar a profundidade da árvore; por padrão, todos os níveis são incluídos. [1]A representação da “árvore TOC” é alterada em cada formato de saída. Os construtores que geram vários arquivos (por exemplo, HTML) os tratam como uma coleção de hiperlinks. Por outro lado, os construtores que geram um único arquivo (por exemplo, LaTeX, página man, etc.) substituem-no pelo conteúdo dos documentos na árvore TOC.
Considere esse exemplo (obtido da biblioteca da documentação do Python, índice de referência):
.. toctree:: :maxdepth: 2 intro strings datatypes numeric (many more documents listed here)
Serve para dois objetivos:
Tabelas de conteúdos para todos os documentos que forem inseridos, com um nível máximo de profundidade de dois, o que significa um subnível de cabeçalho. Diretivas
toctree
nesses documentos também são levadas em conta.O Sphinx conhece a ordem relativa dos documentos
intro
,strings
e assim por diante, e sabe que eles são filhos do documento mostrado, o índice da biblioteca. A partir dessas informações, ele gera os links “próximo capítulo”, “capítulo anterior” e “capítulo pai”.
Entradas
Os títulos dos documentos em
toctree
serão lidos automaticamente a partir do título do documento referenciado. Se isso não for o que você deseja, você pode especificar um título e alvo explícitos usando uma sintaxe semelhante para hiperlinks de reStructuredText (e sintaxe de referência cruzada do Sphinx). Isso se parece com:.. toctree:: intro All about strings <strings> datatypes
A segunda linha acima terá um link para o documento
strings
, mas usará o título “All about strings” ao invés do título do documentostrings
.Você também pode adicionar links externos, fornecendo uma URL HTTP em vez do nome de documento.
O nome de entrada especial
self
representa o documento que contém a diretiva toctree. Isso é útil se você deseja gerar um “sitemap” a partir da toctree.No final, todos os documentos no diretório fonte (ou subdiretórios) devem ocorrer em alguma diretiva
toctree
; O Sphinx emitirá um aviso se encontrar um arquivo que não está incluído, porque isso significa que esse arquivo não será acessível através da navegação padrão.Usa
exclude_patterns
para excluir explicitamente documentos ou diretórios da construção completamente. Usa os metadados “órfãos” para permitir que um documento seja construído, mas notifica o Sphinx de que não está acessível através de uma toctree.O “documento raiz” (selecionado por
root_doc
) é a “raiz” da hierarquia da árvore TOC. Ele pode ser usado como a página principal da documentação ou como um “índice completo” se você não fornecer a opção:maxdepth:
.Alterado na versão 0.6: Adicionado suporte para links externos e referências a “self”.
Opções
- :class: class names (a list of class names, separated by spaces)¶
Atribui atributos de classe. Esta é uma opção comum. Por exemplo:
.. toctree:: :class: custom-toc
Adicionado na versão 7.4.
- :name: label (text)¶
Um nome de alvo implícito que pode ser referenciado usando
ref
. Esta é uma opção comum. Por exemplo:.. toctree:: :name: mastertoc foo
Adicionado na versão 1.3.
- :caption: (text)¶
Adiciona uma legenda ao toctree. Por exemplo:
.. toctree:: :caption: Table of Contents foo
Adicionado na versão 1.3.
- :numbered:¶
- :numbered: depth
Se você quiser ter números de seção mesmo na saída HTML, adicione a opção
:numbered:
ao toctree top-level. Por exemplo:.. toctree:: :numbered: foo bar
A numeração de seção então começa no cabeçalho de
foo
. Sub-toctrees são numeradas automaticamente (não dê o sinalizadornumbered
para elas).Numerar até uma profundidade específica também é possível, dando a profundidade como um argumento numérico para
numbered
.Adicionado na versão 0.6.
Alterado na versão 1.1: Adicionado o argumento numérico depth.
- :titlesonly:¶
Lista apenas títulos de documentos, não outros títulos do mesmo nível. Por exemplo:
.. toctree:: :titlesonly: foo bar
Adicionado na versão 1.0.
- :glob:¶
Analisa curingas glob em entradas toctree. Todas as entradas são comparadas com a lista de documentos disponíveis, e as correspondências são inseridas na lista em ordem alfabética. Por exemplo:
.. toctree:: :glob: intro* recipe/* *
Isso inclui primeiro todos os documentos cujos nomes começam com
intro
, depois todos os documentos na pastarecipe
e, em seguida, todos os documentos restantes (exceto aquele que contém a diretiva, é claro). [2]Adicionado na versão 0.3.
- :reversed:¶
Inverte a ordem das entradas na lista. Isso é particularmente útil ao usar a opção
:glob:
.Adicionado na versão 1.5.
Um toctree oculto define apenas a hierarquia do documento. Ele não inserirá links no documento no local da diretiva.
Isso faz sentido se você tiver outros meios de navegação, por exemplo, por meio de links manuais, navegação na barra lateral HTML ou se você usar a opção
:includehidden:
na toctree de nível superior.Adicionado na versão 0.6.
Se você quiser uma tabela de conteúdo global mostrando a estrutura completa do documento, você pode adicionar a opção
:includehidden:
à diretiva toctree top-level. Todas as outras toctrees em páginas filhas podem então ser tornadas invisíveis com a opção:hidden:
. A toctree de nível superior com:includehidden:
incluirá então suas entradas.Adicionado na versão 1.2.
Nomes especiais¶
Sphinx reserva alguns nomes de documentos para seu próprio uso; não tente criar documentos usando esses nomes – isso irá causar problemas.
Nomes especiais de documentos (e páginas geradas para eles) são:
genindex
Isto é usado para o índice geral, que é preenchido com entradas das diretivas
index
e todas as descrições de objetos geradoras de índice. Por exemplo, veja Índice do Sphinx.modindex
Isso éusado para o índice de módulo Python contém uma entrada por diretiva
py:module
. Por exemplo, veja o Índice de Módulos Python do Sphinx.search
Isso éusado para a página de pesquisa, que contém um formulário que usa o índice de pesquisa em JSON gerado e JavaScript para pesquisa de texto inteiro em documentos gerados por palavras da pesquisa; funciona nos diversos navegadores que oferecem suporte a JavaScript moderno. Por exemplo, veja Página de Busca do Sphinx.
Todo nome começando com
_
Embora poucos desses nomes sejam usados atualmente pelo Sphinx, você não deve criar documentos ou diretórios que contenham documentos com esses nomes. (Usar
_
como um prefixo para um diretório de modelo personalizado é adequado.)
Aviso
Tenha cuidado com caracteres incomuns em nomes de arquivos. Alguns formatos podem interpretar esses caracteres de maneiras inesperadas:
Não use dois pontos
:
para formatos baseados em HTML. Links para outras partes podem não funcionar.Não use o sinal de mais
+
no formato ePub. Alguns recursos podem não ser encontrados.
Marcação de nível de parágrafo¶
Essas diretivas criam parágrafos curtos e podem ser usadas em unidades de informação interna, bem como em texto normal.
Advertências, mensagens e avisos¶
As diretivas de advertência criam elementos de ‘admonition’, um sistema padronizado de comunicação de diferentes tipos de informação, de uma tip
útil a questões de danger
primordial. Essas diretivas podem ser usadas em qualquer lugar que um elemento de corpo comum possa, e podem conter elementos de corpo arbitrários. Há nove advertências específicas nomeadas e a diretiva genérica admonition
.
- .. attention::¶
Informações que exigem a atenção do leitor. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Atenção
Por favor, posso ter sua atenção?
- .. caution::¶
Informações com às quais o leitor deve ter cuidado. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Cuidado
Tenha o devido cuidado.
- .. danger::¶
Informações que podem levar a perigo próximo e presente se não forem atendidas. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Perigo
Que ninguém pense em fugir do perigo, pois cedo ou tarde o amor é seu próprio vingador.
- .. error::¶
Informações relacionadas a modos de falha de alguma descrição. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Erro
ERROR 418: I’m a teapot.
- .. hint::¶
Informações que é útil para o leitor. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Dica
Veja sob o pote de flor.
- .. important::¶
Informações que são de suma importância e que o leitor não deve ignorar. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Importante
Esta é uma declaração de suma importância.
- .. note::¶
Uma informação especialmente importante que o leitor deve saber. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Nota
Esta função não é adequada para enviar latas de presuntos.
- .. tip::¶
Algumas informações úteis para o leitor. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Dica
Lembre-se de usar filtro solar!
- .. warning::¶
Uma informação importante que o leitor deve estar ciente. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Aviso
Cuidado com o cachorro.
- .. admonition:: title¶
Uma advertência genérica, com um título opcional. O conteúdo da diretiva deve ser escrito em frases completas e incluir toda a pontuação apropriada.
Exemplo:
Isso é um título
Este é o conteúdo da advertência.
- .. seealso::¶
Muitas seções incluem uma lista de referências à documentação do módulo ou documentos externos. Essas listas são criadas usando a diretiva
seealso
.A diretiva
seealso
é tipicamente colocada em uma seção logo antes de qualquer subseção. O conteúdo da diretivaseealso
deve ser uma única linha ou uma lista de definições reStructuredText.Exemplo:
.. seealso:: Python's :py:mod:`zipfile` module Documentation of Python's standard :py:mod:`zipfile` module. `GNU tar manual, Basic Tar Format <https://example.org>`_ Documentation for tar archive files, including GNU tar extensions.
Ver também
- Módulo
zipfile
Documentação do módulo padrão
zipfile
.- Manual do GNU tar, Formato básico do Tar
Documentação para arquivos tar, incluindo extensões do GNU tar.
- Módulo
Collapsible text
Adicionado na versão 8.2.
Each admonition directive supports a :collapsible:
option,
to make the content of the admonition collapsible
(where supported by the output format).
This can be useful for content that is not always relevant.
By default, collapsible admonitions are initially open,
but this can be controlled with the open
and closed
arguments
to the :collapsible:
option, which change the default state.
In output formats that don’t support collapsible content,
the text is always included.
For example:
.. note::
:collapsible:
This note is collapsible, and initially open by default.
.. admonition:: Example
:collapsible: open
This example is collapsible, and initially open.
.. hint::
:collapsible: closed
This hint is collapsible, but initially closed.
Nota
This note is collapsible, and initially open by default.
Exemplo
This example is collapsible, and initially open.
Dica
This hint is collapsible, but initially closed.
Descrevendo alterações entre versões¶
- .. versionadded:: version [brief explanation]¶
Esta diretiva documenta a versão do projeto que adicionou o recurso descrito. Quando isso se aplica a todo um módulo ou componente, deve ser colocado no topo da seção relevante antes de qualquer detalhe.
O primeiro argumento deve ser fornecido e é a versão em questão; você pode adicionar um segundo argumento consistindo em uma explicação breve da mudança.
Atenção
Não deve haver nenhuma linha em branco entre o cabeçalho da diretiva e a explicação; isso faz com que esses blocos sejam visualmente contínuos na marcação.
Exemplo:
.. versionadded:: 2.5 The *spam* parameter.
Adicionado na versão 2.5: O parâmetro spam.
- .. versionchanged:: version [brief explanation]¶
Semelhante a
versionadded
, mas descreve quando e o que mudou no recurso nomeado de alguma forma (novos parâmetros, efeitos colaterais alterados, etc.).Exemplo:
.. versionchanged:: 2.8 The *spam* parameter is now of type *boson*.
Alterado na versão 2.8: O parâmetro spam agora é do tipo boson.
- .. deprecated:: version [brief explanation]¶
Semelhante a
versionadded
, mas descreve quando o recurso foi descontinuado. Uma explicação breve também pode ser dada, por exemplo, para dizer ao leitor o que usar em vez disso.Exemplo:
.. deprecated:: 3.1 Use :py:func:`spam` instead.
Obsoleto desde a versão 3.1: Use
spam()
.
- .. versionremoved:: version [brief explanation]¶
Semelhante a
versionadded
, mas descreve quando o recurso foi removido. Uma explicação pode ser fornecida para dizer ao leitor o que usar ou por que o recurso foi removido.Adicionado na versão 7.3.
Exemplo:
.. versionremoved:: 4.0 The :py:func:`spam` function is more flexible, and should be used instead.
Removido na versão 4.0: A função
spam()
é mais flexível e deve ser usada em seu lugar.
Apresentação¶
- .. rubric:: title¶
Um rubric é como um título informal que não corresponde à estrutura do documento, ou seja, não cria um nó de índice.
Nota
Se o title da rubrica for “Notas de rodapé” (ou o equivalente do idioma selecionado), esta rubrica é ignorada pelo escritor de LaTeX, pois presume-se que contenha apenas definições de notas de rodapé e, portanto, criaria um título vazio.
Opções
- :class: class names (a list of class names, separated by spaces)¶
Atribui atributos de classe. Esta é uma opção comum.
- :name: label (text)¶
Um nome de alvo implícito que pode ser referenciado usando
ref
. Esta é uma opção comum.
- :heading-level: n (number from 1 to 6)¶
Adicionado na versão 7.4.1.
Use esta opção para especificar o nível do título do rubric. Neste caso o rubric será renderizado como
<h1>
a<h6>
para saída HTML, ou como o comando de seccionamento não numerado correspondente para LaTeX (vejalatex_toplevel_sectioning
).
- .. centered::¶
Esta diretiva cria uma linha de texto em negrito centralizada.
Obsoleto desde a versão 1.1: Esta diretiva somente para apresentação é um legado de versões anteriores. Use uma diretiva rst-class ao invés e adicione um estilo apropriado.
- .. hlist::¶
Esta diretiva deve conter uma lista com marcadores. Isso a transformará em uma lista mais compacta, distribuindo mais de um item horizontalmente ou reduzindo o espaçamento entre os itens, dependendo do construtor.
Opções
- :columns: n (int)¶
O número de colunas; o padrão é 2. Por exemplo:
.. hlist:: :columns: 3 * A list of * short items * that should be * displayed * horizontally
Adicionado na versão 0.6.
Mostrando exemplos de código¶
Existem várias maneiras de mostrar blocos de código literal com destaque de sintaxe no Sphinx:
usando blocos literais de reStructuredText, opcionalmente em combinação com a diretiva
highlight
;usando a diretiva
code-block
;e usando a diretiva
literalinclude
.
Os blocos de doctest só podem ser usados para mostrar sessões Python interativas, enquanto os três restantes podem ser usados para outras linguagens. Destes três, os blocos literais são úteis quando um documento inteiro, ou pelo menos grandes seções dele, usa blocos de código com a mesma sintaxe e que devem ser estilizados da mesma maneira. Por outro lado, a diretiva code-block
faz mais sentido quando você deseja um controle mais refinado sobre o estilo de cada bloco ou quando você tem um documento contendo blocos de código usando várias sintaxes variadas. Finalmente, a diretiva literalinclude
é útil para incluir arquivos de código inteiros em sua documentação.
Em todos os casos, o realce de sintaxe é fornecido por Pygments. Ao usar blocos literais, isso é configurado usando qualquer diretiva highlight
no arquivo fonte. Quando uma diretiva highlight
é encontrada, ela é usada até que a próxima diretiva highlight
seja encontrada. Se não houver nenhuma diretiva highlight
no arquivo, a linguagem de realce global será usada. O padrão é python
, mas pode ser configurado usando o valor de configuração highlight_language
. Os seguintes valores são suportados:
none
(sem realce)default
(semelhante apython3
, mas com um fallback paranone
sem aviso o realce falha; o padrão quandohighlight_language
não está definido)guess
(deixa Pygments adivinhar o lexador com base no conteúdo, só funciona com certas linguagens bem reconhecíveis)python
rest
c
… e qualquer outro alias de lexador compatível com Pygments
Se o realce com o idioma selecionado falhar (ou seja, o Pygments emitir um token “Error”), o bloco não será realçado de forma alguma.
Importante
A lista de aliases de lexador suportados está vinculada à versão do Pygment. Se quiser garantir um realce consistente, você deve corrigir sua versão do Pygments.
- .. highlight:: language¶
Exemplo:
.. highlight:: c
Esta linguagem é usada até que a próxima diretiva
highlight
seja encontrada. Conforme discutido anteriormente, language pode ser qualquer alias de lexador suportado pelo Pygments.Opções
- :linenothreshold: threshold (number (optional))¶
Habilite a geração de números de linha para blocos de código.
Esta opção utiliza um número opcional como parâmetro de limite. Se for fornecido algum limite, a diretiva produzirá números de linha apenas para os blocos de código maiores que N linhas. Se não for fornecido, os números de linha serão produzidos para todos os blocos de código.
Exemplo:
.. highlight:: python :linenothreshold: 5
- :force: (no value)¶
Se fornecido, pequenos erros no realce serão ignorados.
Adicionado na versão 2.1.
- .. code-block:: [language]¶
- .. sourcecode:: [language]¶
- .. code:: [language]¶
Exemplo:
.. code-block:: ruby Some Ruby code.
O nome alternativo da diretiva
sourcecode
também funciona. Esta diretiva leva um nome da linguagem como argumento. Pode ser qualquer alias de lexador suportado por Pygments. Se não for fornecido, a configuração da diretivahighlight
será usada. Se não for definido,highlight_language
será usado. Para exibir um exemplo de código em linha dentro de outro texto, em vez de como um bloco separado, você pode usar o papelcode
.Alterado na versão 2.0: O argumento
language
se torna opcional.Opções
- :linenos: (no value)¶
Habilite a geração de números de linha para o bloco de código:
.. code-block:: ruby :linenos: Some more Ruby code.
- :lineno-start: number (number)¶
Define o número da primeira linha do bloco de código. Se presente, a opção
linenos
também é ativada automaticamente:.. code-block:: ruby :lineno-start: 10 Some more Ruby code, with line numbering starting at 10.
Adicionado na versão 1.3.
- :emphasize-lines: line numbers (comma separated numbers)¶
Enfatiza linhas específicas do bloco de código:
.. code-block:: python :emphasize-lines: 3,5 def some_function(): interesting = False print('This line is highlighted.') print('This one is not...') print('...but this one is.')
Adicionado na versão 1.1.
Alterado na versão 1.6.6: LaTeX tem suporte à opção
emphasize-lines
.
- :force: (no value)¶
Ignore minor errors on highlighting.
Adicionado na versão 2.1.
- :caption: caption of code block (text)¶
Define uma legenda para o bloco de código.
Adicionado na versão 1.3.
- :name: a label for hyperlink (text)¶
Define o nome do alvo implícito que pode ser referenciado usando
ref
. Por exemplo:.. code-block:: python :caption: this.py :name: this-py print('Explicit is better than implicit.')
Para fazer referência cruzada de um bloco de código usando o papel
ref
ounumref
, é necessário que ambos name e caption ser definido. O argumento de name pode então ser dado anumref
para gerar a referência cruzada. Exemplo:See :numref:`this-py` for an example.
Ao usar
ref
, é possível gerar uma referência cruzada com apenas name definido, desde que um título explícito seja fornecido. Exemplo:See :ref:`this code snippet <this-py>` for an example.
Adicionado na versão 1.3.
- :class: class names (a list of class names separated by spaces)¶
Atribui atributos de classe. Esta é uma opção comum.
Adicionado na versão 1.4.
- :dedent: number (number or no value)¶
Retira os caracteres de recuo do bloco de código. Quando o número é fornecido, os N caracteres iniciais são removidos. Quando nenhum argumento é fornecido, os espaços iniciais são removidos via
textwrap.dedent()
. Por exemplo:.. code-block:: ruby :linenos: :dedent: 4 some ruby code
Adicionado na versão 1.3.
Alterado na versão 3.5: Suporte automático a dedent.
- .. literalinclude:: filename¶
Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the
literalinclude
directive. [3] For example, to include the Python source fileexample.py
, use:.. literalinclude:: example.py
O nome do arquivo geralmente é relativo ao caminho do arquivo atual. No entanto, se for absoluto (começando com
/
), é relativo ao diretório fonte superior.General options
- :class: class names (a list of class names, separated by spaces)¶
Atribui atributos de classe. Esta é uma opção comum.
Adicionado na versão 1.4.
- :name: label (text)¶
Um nome de alvo implícito que pode ser referenciado usando
ref
. Esta é uma opção comum.Adicionado na versão 1.3.
- :caption: caption (text)¶
Add a caption above the included content. If no argument is given, the filename is used as the caption.
Adicionado na versão 1.3.
Options for formatting
- :dedent: number (number or no value)¶
Strip indentation characters from the included content. When a number is given, the leading N characters are removed. When no argument given, all common leading indentation is removed (using
textwrap.dedent()
).Adicionado na versão 1.3.
Alterado na versão 3.5: Suporte automático a dedent.
- :tab-width: N (number)¶
Expand tabs to N spaces.
Adicionado na versão 1.0.
- :encoding: (text)¶
Explicitly specify the encoding of the file. This overwrites the default encoding (
source_encoding
). For example:.. literalinclude:: example.txt :encoding: latin-1
Adicionado na versão 0.4.3.
- :linenos: (no value)¶
Show line numbers alongside the included content. By default, line numbers are counted from 1. This can be changed by the options
:lineno-start:
and:lineno-match:
.
- :lineno-start: number (number)¶
Set line number for the first line to show. If given, this automatically activates
:linenos:
.
- :lineno-match:¶
When including only parts of a file and show the original line numbers. This is only allowed only when the selection consists of contiguous lines.
Adicionado na versão 1.3.
- :emphasize-lines: line numbers (comma separated numbers)¶
Emphasise particular lines of the included content. For example:
.. literalinclude:: example.txt :emphasize-lines: 1,2,4-6
- :language: language (text)¶
Select a highlighting language (Pygments lexer) different from the current file’s standard language (set by
highlight
orhighlight_language
).
- :force: (no value)¶
Ignore minor errors in highlighting.
Adicionado na versão 2.1.
Options for selecting the content to include
- :pyobject: object (text)¶
For Python files, only include the specified class, function or method:
.. literalinclude:: example.py :pyobject: Timer.start
Adicionado na versão 0.6.
- :lines: line numbers (comma separated numbers)¶
Specify exactly which lines to include:
.. literalinclude:: example.py :lines: 1,3,5-10,20-
This includes line 1, line 3, lines 5 to 10, and line 20 to the end.
Adicionado na versão 0.6.
- :start-at: text¶
- :start-after: text¶
- :end-before: text¶
- :end-at: text¶
Another way to control which part of the file is included is to use the
start-after
andend-before
options (or only one of them). Ifstart-after
is given as a string option, only lines that follow the first line containing that string are included. Ifend-before
is given as a string option, only lines that precede the first lines containing that string are included. Thestart-at
andend-at
options behave in a similar way, but the lines containing the matched string are included.start-after
/start-at
andend-before
/end-at
can have same string.start-after
/start-at
filter lines before the line that contains the option string (start-at
will keep the line). Thenend-before
/end-at
filter lines after the line that contains the option string (end-at
will keep the line andend-before
skip the first line).Adicionado na versão 0.6: Added the
start-after
andend-before
options.Adicionado na versão 1.5: Adicionadas as opções
start-at
eend-at
.Dica
To only select
[second-section]
of an INI file such as the following, use:start-at: [second-section]
and:end-before: [third-section]
:[first-section] var_in_first=true [second-section] var_in_second=true [third-section] var_in_third=true
These options can be useful when working with tag comments. Using
:start-after: [initialise]
and:end-before: [initialised]
keeps the lines between between the two comments below:if __name__ == "__main__": # [initialise] app.start(":8000") # [initialised]
When lines have been selected in any of the ways described above, the line numbers in
emphasize-lines
refer to these selected lines, counted consecutively starting from 1.
- :prepend: line (text)¶
Prepend a line before the included code. This can be useful for example when highlighting PHP code that doesn’t include the
<?php
or?>
markers.Adicionado na versão 1.0.
- :append: line (text)¶
Append a line after the included code. This can be useful for example when highlighting PHP code that doesn’t include the
<?php
or?>
markers.Adicionado na versão 1.0.
- :diff: filename¶
Show the diff of two files. For example:
.. literalinclude:: example.txt :diff: example.txt.orig
This shows the diff between
example.txt
andexample.txt.orig
with unified diff format.Adicionado na versão 1.3.
Alterado na versão 0.6: Added support for absolute filenames.
Alterado na versão 1.6: Com
start-after
elines
em uso, a primeira linha destart-after
é considerada como sendo o número de linha1
paralines
.
Glossário¶
- .. glossary::¶
Esta diretiva deve conter uma marcação semelhante a uma lista de definições reStructuredText com termos e definições. As definições serão então referenciáveis com o papel
term
. Exemplo:.. glossary:: environment A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents. source directory The directory which, including its subdirectories, contains all source files for one Sphinx project.
Em contraste com as listas de definição regulares, são permitidos múltiplos termos por entrada e a marcação em linha é permitida em termos. Você pode vincular todos os termos. Por exemplo:
.. glossary:: term 1 term 2 Definition of both terms.
(Quando o glossário está ordenado, o primeiro termo determina a ordem de classificação.)
Se você deseja especificar uma “chave de agrupamento” para entradas de índice geral, você pode colocar uma “chave” como “termo : chave”. Por exemplo:
.. glossary:: term 1 : A term 2 : B Definition of both terms.
Observe que “chave” é usada para agrupar a chave como está. A “chave” não está normalizada; as chaves “A” e “a” tornam-se grupos diferentes. Os caracteres inteiros em “chave” são usados em vez do primeiro caractere; é usado para a chave de agrupamento “Combining Character Sequence” e “Surrogate Pairs”.
Na situação de i18n, você pode especificar “termo localizado : chave” mesmo que o texto original tenha apenas a parte “termo”. Neste caso, o “termo localizado” traduzido será categorizado no grupo “chave”.
Alterado na versão 1.1: Agora oferece suporte a vários termos e marcação embutida em termos.
Alterado na versão 1.4: A chave de índice para o termo do glossário deve ser considerada experimental.
Opções
- :sorted:¶
Ordena as entradas alfabeticamente.
Adicionado na versão 0.6.
Alterado na versão 4.4: Na documentação internacionalizada, ordena de acordo com os termos traduzidos.
Marcação Meta-Informação¶
- .. sectionauthor:: name <email>¶
Identifica o autor da seção corrente. O argumento deve incluir nome do autor que será usado na apresentação do endereço de email. O nome do domínio deve ser minúsculo. Exemplo:
.. sectionauthor:: Guido van Rossum <[email protected]>
Por padrão, essa marcação não é refletida na saída de forma alguma (ela ajuda a acompanhar as contribuições), mas você pode definir o valor de configuração
show_authors
comoTrue
para fazê-los produzir um parágrafo na saída.
- .. codeauthor:: name <email>¶
A diretiva
codeauthor
, na qual podem aparecer diversas vezes nomes dos autores do código descrito, como nome de autor(es)sectionauthor
dos pedaços de documentação. Só haverá saída se o valor deshow_authors
forTrue
.
Marcação geração índice¶
O Sphinx cria automaticamente entradas de índice a partir de todas as descrições de objetos (como funções, classes ou atributos) como discutido em Domínios.
Contudo, também existe marcação disponível, para tornar o índice mais abrangente e habilitar entradas no índice nos documentos onde a informação não está contida nas unidades de informação, como referência ao idioma.
- .. index:: <entries>¶
Essa diretiva contem uma ou mais entradas no índice. Cada entrada consiste de um tipo e valor, separado por dois pontos.
Por exemplo:
.. index:: single: execution; context pair: module; __main__ pair: module; sys triple: module; search; path seealso: scope The execution context --------------------- ...
A diretiva contém cinco entradas, as quais serão convertidas em entradas no índice gerado com link exato para o local onde está o comando de indexação (em caso de mídia offline, corresponde ao número da página).
Como diretivas de índice geram alvos de referências-cruzadas em suas localizações no fonte, faz sentido colocar essas antes do objeto ao qual se referem. ex: cabeçalho, como no exemplo acima.
Os tipos de entrada podem ser:
- simples
Cria uma única entrada de índice. Pode ser feita uma subentrada separando o texto da subentrada com um ponto e vírgula (esta notação também é usada abaixo para descrever quais entradas são criadas). Exemplos:
.. index:: single: execution single: execution; context
single: execution
cria uma entrada de índice chamadaexecution
.single: execution; context
cria uma subentrada deexecution
chamadacontext
.
- par
Um atalho para criar duas entradas de índice. O par de valores deve ser separado por ponto e vírgula. Exemplo:
.. index:: pair: loop; statement
Isto criaria duas entradas de índice;
loop; statement
estatement; loop
.- triplo
Um atalho para criar três entradas de índice. Todos os três valores devem ser separados por ponto e vírgula. Exemplo:
.. index:: triple: module; search; path
Isto criaria três entradas de índice;
module; search path
,search; path, module
epath; module search
.- ver
Um atalho para criar uma entrada de índice que se refere a outra entrada. Exemplo:
.. index:: see: entry; other
Isto criaria uma entrada de índice referente a
entry
paraother
(ou seja, ‘entry’: Veja ‘other’).- ver também
Como
see
, mas insere ‘see also’ em vez de ‘see’.- módulo, palavra chave, operador, objeto, exceção, comando, função interna
Todos esses atalhos descontinuados criam duas entradas de índice. Por exemplo,
module: hashlib
cria as entradasmodule; hashlib
ehashlib; module
.Obsoleto desde a versão 1.0: Esses tipos de entrada específicos do Python estão descontinuados.
Alterado na versão 7.1: Versão de remoção definida como Sphinx 9.0. Usar esses tipos de entrada agora emitirá avisos com a categoria
index
.
Marcar entradas no índices “main” através da prefixação com ponto de exclamação “!”. Referências as entradas principais são enfatizadas e geradas no índice. Por examplo, se duas páginas contêm:
.. index:: Python
e uma página contém:
.. index:: ! Python
então a ligação com outra página é enfatizada dentre a estrutura de links.
Para diretivas de índice contendo somente entradas “simples”, existe uma notação com sintaxe curta:
.. index:: BNF, grammar, syntax, notation
Isso cria quatro entradas no índice.
Alterado na versão 1.1: Adicionado tipos “ver” e “ver também”, bem como marcando entradas principais.
Opções
- :name: a label for hyperlink (text)¶
Define o nome do alvo implícito que pode ser referenciado usando
ref
. Por exemplo:.. index:: Python :name: py-index
Adicionado na versão 3.0.
- :index:¶
Enquanto a diretiva
index
é uma marca em nível de bloco e o link aponta para o começo do próximo parágrafo, também uma regra que configura diretamente onde o alvo do link é usado.O contexto da regra pode ser uma simples frase, a qual existe no text e é usada como ponto de entrada. Também pode haver uma combinação do text e entrada no índice, com estilo explícito em referências cruzadas. Nesse caso parte do “alvo” pode ser uma entrada completa como descrito na diretiva acima. Por exemplo:
This is a normal reStructuredText :index:`paragraph` that contains several :index:`index entries <pair: index; entry>`.
Adicionado na versão 1.1.
Tabelas¶
Usar reStructuredText tables, ex. qualquer
grid sintaxe tabela (ref),
sintaxe tabela simples (ref),
csv-table sintaxe,
ou list-table sintaxe.
A diretiva table serve como sobreposição opcional da sintaxe grid e simple.
Eles funcionam bem na saída HTML, mas renderizar tabelas para LaTeX é complexo. Confira o latex_table_style
.
Alterado na versão 1.6: Células mescladas (várias linhas, múltiplas colunas, ambas) de tabelas de grade contendo conteúdos complexos, como vários parágrafos, citações em bloco, listas, blocos literais, serão renderizadas corretamente na saída LaTeX.
- .. tabularcolumns:: column spec¶
Esta diretiva influencia apenas a saída do LaTeX para a próxima tabela no código-fonte. O argumento obrigatório é uma especificação de coluna (conhecida como “preâmbulo de alinhamento” no idioma LaTeX). Por favor, consulte a documentação do LaTeX, como a página wiki, para obter informações básicas sobre essa especificação de coluna.
Adicionado na versão 0.3.
Nota
tabularcolumns
entra em conflito com a opção:widths:
das diretivas de tabela. Se ambos forem especificados, a opção:widths:
será ignorada.O Sphinx irá renderizar tabelas com mais de 30 linhas com
longtable
. Além dos especificadores de colunasl
,r
,c
ep{width}
, também é possível usar\X{a}{b}
(novo no versão 1.5) que configura a largura da coluna como uma fraçãoa/b
da largura total da linha e\Y{f}
(novo na versão 1.6) ondef
é um decimal: por exemplo\Y{0.2}
significa que a coluna ocupará0.2
vezes a largura da linha.Quando esta diretiva é usada para uma tabela com no máximo 30 linhas, o Sphinx irá renderizá-la com
tabulary
. Pode-se então usar tipos de colunas específicosL
(esquerda),R
(direita),C
(centralizado) eJ
(justificado). Eles têm o efeito de ump{width}
(ou seja, cada célula é um LaTeX\parbox
) com o alinhamento interno do texto especificado e umawidth
calculada automaticamente.Aviso
Células que contêm elementos semelhantes a listas, como descrições de objetos, aspas ou qualquer tipo de lista, não são compatíveis com os tipos de coluna
LRCJ
. O tipo de coluna deve então ser algump{width}
com umawidth
explícita (ou\X{a}{b}
ou\Y{f}
).Blocos literais não funcionam com
tabulary
. O Sphinx retornará aos ambientestabular
oulongtable
e gerará uma especificação de coluna adequada.
Na ausência da diretiva tabularcolumns
, e para uma tabela com no máximo 30 linhas e sem células problemáticas como descrito no aviso acima, o Sphinx usa tabulary
e o tipo de coluna J
para cada coluna.
Alterado na versão 1.6: Anteriormente, o tipo de coluna L
era usado (o texto fica alinhado à esquerda). Para reverter isso, inclua \newcolumntype{T}{L}
no preâmbulo do LaTeX, pois na verdade o Sphinx usa T
e o define por padrão como um alias de J
.
Dica
Um problema frequente com tabulary
é que colunas com pouco conteúdo parecem estar “comprimidas”. Pode-se adicionar ao preâmbulo do LaTeX, por exemplo, \setlength{\tymin}{40pt}
para garantir uma largura mínima de coluna de 40pt
, sendo o padrão tabulary
de 10pt
também pequeno.
Dica
Para forçar o uso do ambiente LaTeX longtable
,. passe longtable
como uma opção :class:
para table, csv-table ou list-table. Use rst-class para outras tabelas.
Mathemática¶
A linguagem de entrada para matemática é marcação LaTeX. É de fato um padrão para notação matemática em texto simples e possui a vantagem de não precisar de tradução adicional para saída LaTeX.
Lembre-se quando introduzir simbolos matemáticos em Python docstrings lidas por autodoc
, deve usar ou duplas barras invertidas ou usar string Python do tipo raw (r"raw"
).
- .. math::¶
Diretiva para math exibida (math controla toda a linha por si).
A diretiva suporta múltiplas equações, que devem estar separadas por linhas em branco:
.. math:: (a + b)^2 = a^2 + 2ab + b^2 (a - b)^2 = a^2 - 2ab + b^2
Adicionalmente, cada simples equação é configurada com ambiente
split
, que significa que deve haver múltiplas linhas alinhadas na equação, alinhada em&
e separada por\\
:.. math:: (a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2
Para maiores detalhes, veja a documentação em AmSMath LaTeX package.
Quando math é somente uma linha de texto, também pode ser usada como argumento de diretiva:
.. math:: (a + b)^2 = a^2 + 2ab + b^2
Opções
- :class: class names (a list of class names, separated by spaces)¶
Atribui atributos de classe. Esta é uma opção comum.
- :name: label (text)¶
Um nome de alvo implícito que pode ser referenciado usando
ref
. Esta é uma opção comum.
- :label: label (text)¶
Normalmente equações não são numeradas. Se desejar que as equações tenham um número, usar opção
label
. Quando utilizada, irá ser escolhido um rótulo interno para a equação, através do qual poderá ser referenciada e vai causar o uso de número de equação. Vereq
para exemplo. O estilo de numeração depende do formato de saída.
- :no-wrap:¶
Evita qualquer quebra no ambiente math. Quando usar essa opção, certifique-se que math está configurada corretamente. Por exemplo:
.. math:: :no-wrap: \begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray}
Alterado na versão 8.2: The directive option
:nowrap:
was renamed to:no-wrap:
.The previous name has been retained as an alias, but will be deprecated and removed in a future version of Sphinx.
Ver também
- Suporte matemático para saídas HTML no Sphinx
Opções de renderização para matemática com construtores HTML.
latex_engine
Explica como configurar o construtor LaTeX para oferecer suporte a literais Unicode na marcação matemática.
Exibições de produção gramatical¶
Marcação especial está disponível para exibir as produções de uma gramática formal. A marcação é simples e não tenta modelar todos os aspectos da BNF (ou quaisquer formas derivadas), mas fornece o suficiente para permitir que gramáticas livres de contexto sejam exibidas de uma forma que faça com que os usos de um símbolo sejam renderizados como hiperlinks para a definição do símbolo. Existe esta diretiva:
- .. productionlist:: [productionGroup]¶
Esta diretiva é usada para incluir um grupo de produções. Cada produção é fornecida em uma única linha e consiste em um nome, separado por dois pontos da definição a seguir. Se a definição abranger várias linhas, cada linha de continuação deverá começar com dois pontos colocados na mesma coluna da primeira linha. Linhas em branco não são permitidas nos argumentos da diretiva
productionlist
.A definição pode conter nomes de tokens que são marcados como texto interpretado (por exemplo, “
soma ::= `integer` "+" `integer`
”) – isso gera referências cruzadas para as produções desses tokens. Fora da lista de produção, você pode fazer referência a produções de tokens usandotoken
.O argumento productionGroup para
productionlist
serve para distinguir diferentes conjuntos de listas de produção que pertencem a diferentes gramáticas. Várias listas de produção com o mesmo productionGroup definem, portanto, regras no mesmo escopo.Dentro da lista de produção, os tokens referem-se implicitamente às produções do grupo atual. Você pode se referir à produção de outra gramática prefixando o token com seu nome de grupo e dois pontos, por exemplo, “
outroGrupo:soma
”. Se o grupo do token não deve ser mostrado na produção, ele pode ser prefixado com um til, por exemplo, “~outroGrupo:soma
”. Para se referir a uma produção de uma gramática sem nome, o token deve ser prefixado por dois pontos, por exemplo, “:soma
”.Fora da lista de produção, se você forneceu um argumento grupoProdução você deve prefixar o nome do token na referência cruzada com o nome do grupo e dois pontos, por exemplo, “
meuGrupo:soma
” em vez de apenas “soma
”. Se o grupo não deve ser mostrado no título do link, um título explícito pode ser fornecido (por exemplo, “meuTítulo <meuGrupo:soma>
”) ou o alvo pode ser prefixado com um til (por exemplo, “~meuGrupo:soma
”).Observe que nenhuma análise adicional de reStructuredText é feita na produção, então você não precisa escapar dos caracteres
*
ou|
.
A seguir está um exemplo retirado do Manual de Referência do Python:
.. productionlist::
try_stmt: try1_stmt | try2_stmt
try1_stmt: "try" ":" `suite`
: ("except" [`expression` ["," `target`]] ":" `suite`)+
: ["else" ":" `suite`]
: ["finally" ":" `suite`]
try2_stmt: "try" ":" `suite`
: "finally" ":" `suite`
Notas de Rodapé