sphinx.ext.linkcode - Adiciona links externos ao código-fonte

Autor do módulo: Pauli Virtanen

Adicionado na versão 1.2.

Essa extensão examina as descrições de objetos (.. class::, .. function:: etc.) e adiciona links externos ao código hospedado em algum lugar da web. A intenção é semelhante à extensão sphinx.ext.viewcode, mas assume que o código-fonte pode ser encontrado em algum lugar na Internet.

Em sua configuração, você precisa especificar uma função linkcode_resolve que retorna uma URL baseada no objeto.

Configuração

linkcode_resolve
Type:
Callable[[str, dict[str, str]], str | None] | None
Default:
None

Esta é uma função linkcode_resolve(domain, info), que deve retornar a URL para o código-fonte correspondente ao objeto em determinado domínio com informações dadas.

A função deve retornar None se nenhum link for adicionado.

O argumento domain especifica o domínio da linguagem em que o objeto está. info é um dicionário com as seguintes chaves garantidas para estarem presentes (dependendo do domínio):

  • py: module (nome do módulo), fullname (nome do objeto)

  • c: names (lista de nomes para o objeto)

  • cpp: names (lista de nomes para o objeto)

  • javascript: object (nome do objeto), fullname (nome do item)

Exemplo:

def linkcode_resolve(domain, info):
    if domain != 'py':
        return None
    if not info['module']:
        return None
    filename = info['module'].replace('.', '/')
    return "https://somesite/sourcerepo/%s.py" % filename

Domínios de terceiros

O suporte para outros domínios pode ser adicionado por extensões com add_linkcode_domain(). Por exemplo, uma extensão Sphinx que fornece um domínio php poderia usar o seguinte código para oferecer suporte a linkcode:

from sphinx.ext.linkcode import add_linkcode_domain

def setup(app):
    add_linkcode_domain('php', ['namespace', 'class', 'fullname'])
sphinx.ext.linkcode.add_linkcode_domain(domain: str, keys: list[str], override: bool = False) → None[código-fonte]

Registra uma nova lista de chaves para usar para um domínio.

Adicionado na versão 8.2.