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

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.

The unique identifier can be used in the external role, so that it is clear which intersphinx set the target belongs to. A link like :external+python:ref:`comparison manual <comparisons>` will link to the label “comparisons” in the doc set “python”, if it exists.

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_cache_limit

O número máximo de dias para manter em cache inventários. O padrão é 5, cinco dias. Valores negativos indicam tempo indeterminado.

intersphinx_timeout

O número de segundos para o tempo limite. O padrão é None, ou seja, não sem tempo de limite.

Nota

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

intersphinx_disabled_reftypes

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 *.

O valor padrão é ['std:doc'].

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:password@docs.python.org/3',
                                  None)}

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