sphinx.ext.intersphinx – Link para documentação outros projetos

Adicionado na versão 0.5.

Esta extensão pode gerar links para a documentação de objetos em projetos externos, seja explicitamente através do papel external, ou como uma resolução de fallback para qualquer outra referência cruzada.

O uso para resolução de fallback é simples: sempre que o Sphinx encontra uma referência cruzada que não tem um alvo correspondente no conjunto de documentação atual, ele procura alvos nos conjuntos de documentação externa configurados em intersphinx_mapping. Uma referência como :py:class:`zipfile.ZipFile` pode ser vinculada à documentação do Python para a classe ZipFile, sem que você precise especificar onde ela está localizada exatamente.

Ao usar o papel external, você pode forçar a pesquisa para qualquer projeto externo e, opcionalmente, para um projeto externo específico. Um link como :external:ref:`comparison manual <comparisons>` será vinculado ao rótulo “comparações” em qualquer projeto externo configurado, se existir, e um link como :external+python:ref:`manual de comparação <comparisons>` irá vincular ao rótulo “comparações” apenas no conjunto de documentos “python”, se existir.

Por trás do palco, isso funciona como:

  • Cada Sphinx HTML constrói um nome de arquivo chamado objects.inv que contém o mapeamento dos nomes de objetos para URIs relativas a conjunto raiz HTML.

  • Projetos usando a extensão Intersphinx podem especificar a localização de tais arquivos de mapeamento no valor de configuração intersphinx_mapping. O mapeamento será então usado para resolver ambas as referências external, e também referências ausentes a objetos em links para outra documentação.

  • Por padrão, o mapeamento arquivo é assumido como no mesmo local da documentação; entretanto o local do mapeamento do arquivo também pode ser especificado individualmente, por exemplo, se o documento for construído sem acesso à internet.

Configuração

Para usar a ligação Intersphinx, adicione 'sphinx.ext.intersphinx' ao seu valor de configuração extensions, e use estes valores de configuração para ativar a vinculação:

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

Esse valor config. irá conter os locais e nomes de outros projetos que podem ser ligadas a essa documentação.

Caminhos e locais relativos são assumidos como relativos a documentação base, enquanto caminhos relativos em locais inventariados são relativos ao diretório fonte.

Quando recuperando arquivos remotos, configurações de proxy irão ser lidas da variável de ambiente $HTTP_PROXY.

Formato

Adicionado na versão 1.0.

Um dicionário mapeando identificadores exclusivos para uma tupla (target, inventory). Cada target é o URI base de um conjunto de documentação Sphinx estrangeira e pode ser um caminho local ou um URI HTTP. O inventory indica onde o arquivo de inventário pode ser encontrado: pode ser None (um arquivo objects.inv no mesmo local que o URI base) ou outro caminho de arquivo local ou um URI HTTP completo para um arquivo de inventário.

O identificador exclusivo pode ser usado no papel external, para que fique claro a qual interesphinx definido o alvo pertence. Um link como :external+python:ref:`comparison manual <comparisons> será vinculado ao rótulo “comparações” no conjunto de documentação “python”, se existir.

Exemplo

Para adicionar ligações aos módulos e objetos na biblioteca documentação padrão Python, usar:

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

Isso irá baixar arquivo correspondente a objects.inv da internet e gerar links para as páginas sob determinada URI. O respectivo inventário é mantido em cache no ambiente Sphinx, portanto deve ser baixado novamente quando fizer um rebuild completo.

Segundo exemplo, exibindo o significado de um valor não None no segundo item do par:

intersphinx_mapping = {'python': ('https://docs.python.org/3',
                                  'python-inv.txt')}

Isso irá ler o inventário de python-inv.txt no diretório de origem, mas ainda gerará links para as páginas em https://docs.python.org/3. Cabe a você atualizar o arquivo de inventário à medida que novos objetos são adicionados à documentação do Python.

Vários alvos para o inventário

Adicionado na versão 1.3.

Arquivos alternativos podem ser especificados para cada inventário. Alguém pode ter um par como segunda opção como no seguinte exemplo. Irá ler o inventário interagindo através do segundo par do conjunto até que ocorra a primeira recuperação com sucesso. Uso principal disso é para especificar espelhos quando o servidor primário estiver fora de serviço:

intersphinx_mapping = {'python': ('https://docs.python.org/3',
                                  (None, 'python-inv.txt'))}

Para um conjunto de livros editados e testados localmente e depois publicados juntos, pode ser útil experimentar primeiro um arquivo de inventário local, para verificar as referências antes da publicação:

intersphinx_mapping = {
    'otherbook':
        ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
            ('../../otherbook/build/html/objects.inv', None)),
}
intersphinx_resolve_self
Type:
str
Default:
''

Se fornecido, intersphinx_resolve_self substitui o mecanismo de resolução do intersphinx para resolver todas as referências ao projeto atual, em vez de uma referência externa. Isso é útil quando a documentação é compartilhada entre projetos, com o projeto ‘upstream’ ou ‘parent’ usando referências no estilo intersphinx em sua documentação. Por exemplo, um projeto como Astropy pode definir:

intersphinx_resolve_self = 'astropy'

Projetos que reutilizam a documentação do Astropy ou herdam suas docstrings configurariam então seu intersphinx_mapping com uma chave 'astropy', apontando para objects.inv do astropy. Por exemplo:

intersphinx_mapping = {
    'astropy': ('https://docs.astropy.org/en/stable/', None),
}
intersphinx_cache_limit
Type:
int
Default:
5 (five days)

O número máximo de dias para manter em cache inventários. Defina isso para um valor negativo para manter inventários por tempo indeterminado.

intersphinx_timeout
Type:
int | float | None
Default:
None

O número de segundos para o tempo limite. Use None para nenhum tempo limite.

Nota

o timeout não é um limite de tempo para todo o download da resposta; em vez disso, uma exceção é levantada se o servidor não tiver emitido uma resposta para os segundos de timeout.

intersphinx_disabled_reftypes
Type:
Sequence[str]
Default:
['std:doc']

Adicionado na versão 4.3.

Alterado na versão 5.0: Valor padrão alterado de uma lista vazia para ['std:doc'].

Uma lista de strings sendo:

  • o nome de um tipo de referência específica em um domínio, p. ex., std:doc, py:func ou cpp:class,

  • o nome de um domínio e um coringa, p. e.g., std:*, py:* ou cpp:*, ou

  • simplesmente um coringa *.

Quando uma referência cruzada não-external estiver sendo resolvida por interesphinxes, pule a resolução se ela corresponder a uma das especificações nesta lista.

Por exemplo, com intersphinx_disabled_reftypes = ['std:doc'] uma referência cruzada :doc:`installation` não será tentada para ser resolvida por intersphinx, mas :external+otherbook:doc:`installation` será tentado a ser resolvido no inventário chamado otherbook em intersphinx_mapping. Ao mesmo tempo, todas as referências cruzadas geradas em, por exemplo, declarações do Python, ainda serão tentadas para serem resolvidas por interesphinx.

Se * estiver na lista de domínios, nenhuma referência não-external será resolvida por intersphinx.

Referenciar explicitamente objetos externos

A extensão Intersphinx fornece o seguinte papel.

:external:

Adicionado na versão 4.4.

Use o Intersphinx para realizar a pesquisa apenas em projetos externos e não no projeto atual. O Intersphinx ainda precisa saber o tipo de objeto que você gostaria de encontrar, então a forma geral desse papel é escrever a referência cruzada como se o objeto estivesse no projeto atual, mas depois prefixe-o com :external . As duas formas são então

  • :external:domain:reftype:`alvo`, p. ex., :external:py:class:`zipfile.ZipFile`, ou

  • :external:reftype:`target`, por exemplo :external:doc:`installation`. Com este atalho, o domínio é assumido como std.

Se você deseja restringir a pesquisa a um projeto externo específico, a chave do projeto, conforme especificado em intersphinx_mapping, também é adicionada para obter os dois formulários

  • :external+invname:domain:reftype:`alvo`, p. ex., :external+python:py:class:`zipfile.ZipFile` ou

  • :external+invname:reftype:`alvo`, p. ex., :external+python:doc:`installation`.

Usando Intersphinx com arquivo de inventário sob autorização básica

Intersphinx oferece suporte a autorização básica assim:

intersphinx_mapping = {'python': ('https://user:[email protected]/3',
                                  None)}

O usuário e a senha serão retirados da URL ao gerar os links.