sphinx.ext.autosectionlabel – Permite referenciar seções por seu título

Adicionado na versão 1.4.

Por padrão, referências cruzadas para seções usam rótulos (veja ref). Esta extensão permite que você se refira às seções pelo título delas.

Por exemplo:

A Plain Title
-------------

This is the text of the section.

It refers to the section title, see :ref:`A Plain Title`.

Internamente essa extensão gera rótulos para cada seção. Se os mesmos nomes da seção são usados em todo o documento, qualquer um será vinculado por padrão. A variável de configuração autosectionlabel_prefix_document pode ser usada para construir cabeçalhos que aparecem múltiplas vezes mas em diferentes documentos únicos.

Configuração

autosectionlabel_prefix_document
Type:
bool
Default:
False

Verdadeiro para cada prefixo ou rótulo com o nome do documento, seguido por dois pontos. Por exemplo, index:Introduction para uma seção chamada Introduction que aparece no documento index.rst. Útil para evitar ambiguidade quando cabeçalho da seção aparece em diferentes documentos.

autosectionlabel_maxdepth
Type:
int | None
Default:
None

Se definido, autosectionlabel escolhe as seções para rotulagem por sua profundidade. Por exemplo, quando o conjunto 1 para autosectionlabel_maxdepth, os rótulos são gerados apenas para as seções de nível superior e as seções mais profundas não são rotuladas. O padrão é None (ou seja, todas as seções são rotuladas).

Depuração

O WARNING: undefined label indica que sua referência em ref está escrita incorretamente. Invocar sphinx-build com -vvv (veja -v) irá imprimir todos os nomes de seções e os rótulos que foram gerados para elas. Esta saída pode ajudar a encontrar o rótulo de referência correto.