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 documento strings.

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 sinalizador numbered 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 pasta recipe 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.

:hidden:

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.

:includehidden:

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 diretiva seealso 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

Python’s zipfile module

Documentation of Python’s standard zipfile module.

Manual do GNU tar, Formato básico do Tar

Documentação para arquivos tar, incluindo extensões do GNU tar.

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

.. version-added:: version [brief explanation]
.. 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.

Alterado na versão 9.0: A diretiva versionadded foi renomeada para version-added. O nome anterior foi mantido como um apelido.

Exemplo:

.. version-added:: 2.5
   The *spam* parameter.

Adicionado na versão 2.5: O parâmetro spam.

.. version-changed:: version [brief explanation]
.. versionchanged:: version [brief explanation]

Semelhante a version-added, mas descreve quando e o que mudou no recurso nomeado de alguma forma (novos parâmetros, efeitos colaterais alterados, etc.).

Alterado na versão 9.0: A diretiva versionchanged foi renomeada para version-changed. O nome anterior foi mantido como um apelido.

Exemplo:

.. version-changed:: 2.8
   The *spam* parameter is now of type *boson*.

Alterado na versão 2.8: O parâmetro spam agora é do tipo boson.

.. version-deprecated:: version [brief explanation]
.. deprecated:: version [brief explanation]

Semelhante a version-added, 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.

Alterado na versão 9.0: A diretiva deprecated foi renomeada para version-deprecated. O nome anterior foi mantido como um apelido.

Exemplo:

.. version-deprecated:: 3.1
   Use :py:func:`spam` instead.

Descontinuado desde a versão 3.1: Use spam().

.. version-removed:: version [brief explanation]
.. versionremoved:: version [brief explanation]

Semelhante a version-added, 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.

Alterado na versão 9.0: The versionremoved directive was renamed to version-removed. The previous name is retained as an alias.

Exemplo:

.. version-removed:: 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 (veja latex_toplevel_sectioning).

.. centered::

Esta diretiva cria uma linha de texto em negrito centralizada.

Descontinuado 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:

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 a python3, mas com um fallback para none sem aviso o realce falha; o padrão quando highlight_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 diretiva highlight 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 papel code.

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 ou numref, é necessário que ambos name e caption ser definido. O argumento de name pode então ser dado a numref 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 file example.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 (UTF-8). 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 or highlight_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 and end-before options (or only one of them). If start-after is given as a string option, only lines that follow the first line containing that string are included. If end-before is given as a string option, only lines that precede the first lines containing that string are included. The start-at and end-at options behave in a similar way, but the lines containing the matched string are included.

start-after/start-at and end-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). Then end-before/end-at filter lines after the line that contains the option string (end-at will keep the line and end-before skip the first line).

Adicionado na versão 0.6: Added the start-after and end-before options.

Adicionado na versão 1.5: Adicionadas as opções start-at e end-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 and example.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 e lines em uso, a primeira linha de start-after é considerada como sendo o número de linha 1 para lines.

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 como True 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 de show_authors for True.

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:

single

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 chamada execution.

  • single: execution; context cria uma subentrada de execution chamada context.

pair

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 e statement; loop.

triple

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 e path; module search.

see

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 para other (ou seja, ‘entry’: Veja ‘other’).

seealso

Como see, mas insere ‘see also’ em vez de ‘see’.

module, keyword, operator, object, exception, statement, builtin

Todos esses atalhos descontinuados criam duas entradas de índice. Por exemplo, module: hashlib cria as entradas module; hashlib e hashlib; module.

Descontinuado 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 “single”, 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 see e seealso, 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.

Incluindo conteúdo baseado em tags

.. only:: <expression>

Incluir o conteúdo da diretiva somente se a expressão for verdadeira. A expressão deve consistir de marcas, como essa:

.. only:: html and draft

Tags indefinidas são falsas, tags definidas são verdadeiras (tags podem ser definidas através da opção de linha de comando --tag ou dentro do conf.py, veja aqui). Expressões booleanas (como (latex or html) and draft) são suportadas e podem usar parênteses.

O formato e o nome do construtor corrente (html, latex ou text) são sempre configurados com a marca tag [4]. Para fazer distinção entre formato e o nome explícito, eles são adicionados com o prefixo format_ e builder_, ex: o construtor epub define marcas html, epub, format_html e builder_epub.

Essas tags padrões são configuradas após o arquivo de configuração ter sido lido, portanto não estão disponíveis lá.

Todas as tags devem seguir a sintaxe de identificador padrão do Python, conforme estabelecido na documentação Identificadores e palavras-chave. Ou seja, uma expressão de tag pode consistir apenas em tags que estejam em conformidade com a sintaxe das variáveis ​​Python. Em ASCII, consiste em letras maiúsculas e minúsculas A a Z, o sublinhado _ e, exceto o primeiro caractere, os dígitos 0 a 9.

Adicionado na versão 0.6.

Alterado na versão 1.2: Adicionado o nome do construtor e os prefixos.

Aviso

Essa diretiva é desenhada para controlar sómente conteúdo do documento. Não pode controlar seções, rótulos e outros.

Tabelas

Usar reStructuredText tables, ex. qualquer

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.

Alterado na versão 9.0: The partial support of the LaTeX builder for nesting a table in another has been extended. Formerly Sphinx would raise an error if longtable class was specified for a table containing a nested table, and some cases would not raise an error at Sphinx level but fail at LaTeX level during PDF build. This is a complex topic in LaTeX rendering and the output can sometimes be improved via the tabularcolumns directive.

.. tabularcolumns:: column spec

This directive influences only the LaTeX output, and only for the next table in source. The mandatory argument is a column specification (known as an “alignment preamble” in LaTeX idiom). Please refer to a LaTeX documentation, such as the wiki page, for basics of such a column specification.

Adicionado na versão 0.3.

Sphinx renders tables with at most 30 rows using tabulary (or tabular if at least one cell contains either a code-block or a nested table), and those with more rows with longtable. The advantage of using tabulary is that it tries to compute automatically (internally to LaTeX) suitable column widths.

The tabulary algorithm often works well, but in some cases when a cell contains long paragraphs, the column will be given a large width and other columns whose cells contain only single words may end up too narrow. The tabularcolumns can help solve this via providing to LaTeX a custom “alignment preamble” (aka “colspec”). For example lJJ will be suitable for a three-columns table whose first column contains only single words and the other two have cells with long paragraphs.

Nota

Of course, a fully automated solution would be better, and it is still hoped for, but it is an intrinsic aspect of tabulary, and the latter is in use by Sphinx ever since 0.3… It looks as if solving the problem of squeezed columns could require substantial changes to that LaTeX package. And no good alternative appears to exist, as of 2025.

Dica

A way to solve the issue for all tables at once, is to inject in the LaTeX preamble (see latex_elements) a command such as \setlength{\tymin}{1cm} which causes all columns to be at least 1cm wide (not counting inter-column whitespace). Currently, Sphinx configures \tymin to allow room for three characters at least.

Here is a more sophisticated “colspec”, for a 4-columns table:

.. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38}

This is used in Sphinx own PDF docs at APIs descontinuadas. Regarding column widths, this “colspec” achieves the same as would :widths: option set to 40 10 12 38 but it injects extra effects.

Nota

In case both tabularcolumns and :widths: option of table directives are used, :widths: option will be ignored by the LaTeX builder. Of course it is obeyed by other builders.

Literal blocks do not work at all with tabulary and Sphinx will then fall back to tabular LaTeX environment. It will employ the tabularcolumns specification in that case only if it contains no usage of the tabulary specific column types (which are L, R, C and J).

Besides the LaTeX l, r, c and p{width} column specifiers, and the tabulary specific L, R, C and J, one can also use (with all table types) \X{a}{b} which configures the column width to be a fraction a/b of the total line width and \Y{f} where f is a decimal: for example \Y{0.2} means that the column will occupy 0.2 times the line width.

Alterado na versão 1.6: Sphinx uses J (justified) by default with tabulary, not L (flushed-left). To revert, include \newcolumntype{T}{L} in the LaTeX preamble, as in fact Sphinx uses T and sets it by default to be an alias of J.

Alterado na versão 9.0: Formerly, Sphinx did not use tabulary if the table had at least one cell containing “problematic” elements such as lists, object descriptions, blockquotes (etc…) because such contents are not out-of-the-box compatible with tabulary. At 9.0 a technique, which was already in use for merged cells, was extended to such cases, and the sole “problematic” contents are code-blocks and nested tables. So tables containing (only) cells with multiple paragraphs, bullet or enumerated lists, or line blocks, will now better fit to their contents (if not rendered by longtable). Cells with object descriptions or admonitions will still have a tendency to induce the table to fill the full text area width, but columns in that table with no such contents will be tighter.

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. Ver eq 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

Special markup is available for displaying the productions of a formal grammar. The markup is simple and does not attempt to model all aspects of BNF (or any derived forms), but provides enough to allow context-free grammars to be displayed in a way that causes uses of a symbol to be rendered as hyperlinks to the definition of the symbol. There is this directive:

.. productionlist:: [production_group]

This directive is used to enclose a group of productions. Each production is given on a single line and consists of a name, separated by a colon from the following definition. If the definition spans multiple lines, each continuation line must begin with a colon placed at the same column as in the first line. Blank lines are not allowed within productionlist directive arguments.

The optional production_group directive argument serves to distinguish different sets of production lists that belong to different grammars. Multiple production lists with the same production_group thus define rules in the same scope. This can also be used to split the description of a long or complex grammar across multiple productionlist directives with the same production_group.

The definition can contain token names which are marked as interpreted text, (e.g. “sum ::= `integer` "+" `integer`”), to generate cross-references to the productions of these tokens. Such cross-references implicitly refer to productions from the current group. To reference a production from another grammar, the token name must be prefixed with the group name and a colon, e.g. “other-group:sum”. If the group of the token should not be shown in the production, it can be prefixed by a tilde, e.g., “~other-group:sum”. To refer to a production from an unnamed grammar, the token should be prefixed by a colon, e.g., “:sum”. No further reStructuredText parsing is done in the production, so that special characters (*, |, etc) do not need to be escaped.

Token productions can be cross-referenced outwith the production list by using the token role. If you have used a production_group argument, the token name must be prefixed with the group name and a colon, e.g., “my_group:sum” instead of just “sum”. Standard cross-referencing modifiers may be used with the :token: role, such as custom link text and suppressing the group name with a tilde (~).

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é