sphinx.ext.autosectionlabel – Permite referenciar seção usando seu título

Adicionado na versão 1.4.

Essa extensão permite referenciar a ao título da seção. Isso afeta a regra de referência (ref).

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

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

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 (desativado).

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.