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

Novo na versão 0.5.

Essa extensão pode gerar automaticamente links para documetação de objetos em outros projetos.

Usar é simples: onde o Sphinx encontrar referência cruzada que estiver atendida no corrente documento, irá buscar por alvos no conjunto de documentos configurados em intersphinx_mapping. Referência como :py:class:`zipfile.ZipFile` irá referir a doc. Python de Classe ZipFile, sem conhecer onde ela está localizada.

Quando usando o novo formato (ver abaixo), poderá ser forçada a busca conjunto estrangeiro, configurando apropriadamente o prefixo ao link alvo. Um link como :ref:`manual comparação <python:comparisons>` irá ligar o label “comparação” no doc “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 extensão InterSphinx podem especificar a localização desses arquivos de mapeamento na configuração intersphinx_mapping. O mapeamento irá então ser usado para resolver referências a objetos inexistentes em links para outra documentação.

  • Por padrão, o mapeamento arquivo é assumido como na mesma localização da documentação; entretanto o local do mapeamento do arquivo também pode ser especificado individualmente, ex. se o documento for construído sem acesso a 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 antigo dessa configuração

Esse é o formato usado para config antes do Sphinx 1.0. E permanece válido.

Um dicionário mapeando URIs para None ou para uma URI. As chaves são base da URI para conjuntos de documentação Externa e poder ser caminhos locais ou URIs HTTP. Os valores indicam onde o arquivo de inventário pode ser encontrado: pode ser None (mesmo local da base URI) ou outro local ou URI HTTP.

Novo formato para configurar valores

Novo na versão 1.0.

A dictionary mapping unique identifiers to a tuple (target, inventory). Each target is the base URI of a foreign Sphinx documentation set and can be a local path or an HTTP URI. The inventory indicates where the inventory file can be found: it can be None (an objects.inv file at the same location as the base URI) or another local file path or a full HTTP URI to an inventory file.

Um identificador único pode ser usado para prefixar alvos referências cruzadas, desde que esteja claro a qual conjunto intersphinx pertença. Um link como :ref:`comparação manual <python:comparação>` irá ligar rótulo “comparação” no conjunto doc “python”, caso exista.

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.

Multiple targets for the inventory

Novo 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'))}

For a set of books edited and tested locally and then published together, it could be helpful to try a local inventory file first, to check references before publication:

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.

Using Intersphinx with inventory file under Basic Authorization

Intersphinx supports Basic Authorization like this:

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

The user and password will be stripped from the URL when generating the links.