sphinx.ext.linkcode – Ajouter des liens externes au code source

Auteur du module : Pauli Virtanen

Ajouté dans la version 1.2.

Cette extension examine les descriptions de vos objets (... classe::, ... fonction:: etc.) et ajoute des liens externes au code hébergé quelque part sur le web. L’intention est similaire à celle de l’extension sphinx.ext.viewcode, mais suppose que le code source peut être trouvé quelque part sur Internet.

Dans votre configuration, vous devez spécifier une fonction linkcode_resolve qui retourne une URL basée sur l’objet.

Configuration

linkcode_resolve
Type:
Callable[[str, dict[str, str]], str | None] | None
Défaut:
None

C’est une fonction linkcode_resolve(domain, info), qui devrait renvoyer l’URL vers le code source correspondant à l’objet dans un domaine donné avec des informations données.

La fonction doit retourner None` si aucun lien n’est à ajouter.

L’argument domain spécifie le domaine de langue dans lequel se trouve l’objet. info` est un dictionnaire avec les clés suivantes garanties pour être présentes (selon le domaine) :

  • py : module (nom du module), fullname (nom de l’objet)

  • c : names (liste des noms pour l’objet)

  • cpp : names (liste des noms pour l’objet)

  • javascript : object (nom de l’objet), fullname (nom de l’élément)

Exemple:

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

Third-party domains

Support for other domains can be added by extensions with add_linkcode_domain(). For example, a Sphinx extension that provides a php domain could use the following code to support 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[source]

Register a new list of keys to use for a domain.

Ajouté dans la version 8.2.