`sphinx.ext.extlinks` – Marcação para encurtar links externos¶

Autor do módulo: Georg Brandl

Adicionado na versão 1.0.

Essa extensão facilita a existência de um padrão comum para diversos links que apontam para uma URL em um site, ex. links para rastrear erros, controle de versão na web ou simples páginas de outros sites. Não fornece apelidos para URLs portanto só é preciso informar o nome da sub-página quando criar o link.

Vamos supor que deseja incluir diversos links para solicitações no Sphinx tracker, em https://github.com/sphinx-doc/sphinx/issues/num. Digitando esse URL novamente em diversos lugares torna-se cansativo, então usar extlinks para evitar repetições.

A extensão adiciona um valor de configuração:

extlinks¶

Type:: dict[str, tuple[str, str | None]]
Default:: {}

Esse valor configurado pode ser um dicionário de sites, mapeamentos únicos para nomes alternativos para uma URL base e uma legenda. Por exemplo, para criar um apelido para os casos acima, podemos adicionar:

extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
                      'issue %s')}

Agora, você pode usar o nome do apelido como um novo papel, por exemplo, :issue:`123`. Isso insere um link para https://github.com/sphinx-doc/sphinx/issues/123. Como você pode ver, o alvo dado no papel é substituído na base URL no lugar de %s.

A legenda do link depende do segundo item da tupla, a caption:

Se caption for None, a legenda do link será a URL completa.
Se caption for uma string, então deve conter %s exatamente uma vez. Neste caso, a legenda do link é caption com a URL parcial substituída por %s – no exemplo acima, a legenda do link seria issue 123.

Para produzir um % literal em base URL ou caption, use %%:

extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
                      '[K&R; page %s]')}

Você também pode usar a sintaxe usual de “título explícito” suportada por outras funções que geram links, ou seja, :issue:`this issue <123>`. Nesse caso, caption não é relevante.

Alterado na versão 4.0: Suporte para substituto por ‘%s’ na legenda.

Nota

Como os links são gerados a partir da leitura da regra em outro estágio, podem aparecer como links comuns ex. construtor linkcheck.

extlinks_detect_hardcoded_links¶

Type:: bool
Default:: False

Se ativado, o extlinks emite um aviso se um link codificado permanentemente for substituível por um extlink e sugere um substituto por meio de um aviso.

Adicionado na versão 4.5.

sphinx.ext.extlinks – Marcação para encurtar links externos¶

`sphinx.ext.extlinks` – Marcação para encurtar links externos¶