Substitutions dans des liens dans reST / Sphinx

Question

J'utilise Sphinx pour documenter un service Web qui sera déployé sur différents serveurs. La documentation est pleine d'exemples d'URL sur lesquels l'utilisateur peut cliquer et ils devraient simplement fonctionner. Mon problème est que l'hôte, le port et la racine de déploiement varieront et que la documentation devra être régénérée à chaque déploiement.

J'ai essayé de définir des substitutions comme ceci:

|base_url|/path
.. |base_url| replace:: http://localhost:8080

Mais le code HTML généré n'est pas ce que je veux (n'inclut pas & "; chemin &"; dans le lien généré):

.

<a href="http://localhost:8080">http://localhost:8080</a>/path

Quelqu'un sait-il comment résoudre ce problème?

Answer 1

Nouveauté de Sphinx v1.0:

sphinx.ext.extlinks & # 8211; Balisage pour raccourcir les liens externes

http://sphinx.pocoo.org/ext/extlinks.html

L'extension ajoute une nouvelle valeur de configuration:

liens externes

Cette valeur de configuration doit être un dictionnaire de sites externes mappant des noms d’alias courts et uniques sur une URL de base et un préfixe. Par exemple, pour créer un alias pour les problèmes mentionnés ci-dessus, ajoutez

extlinks = {'issue': 
    ('http://bitbucket.org/birkenfeld/sphinx/issue/%s', 'issue ')}

Vous pouvez maintenant utiliser le nom d'alias comme nouveau rôle, par exemple. :issue:`123` Ceci insère ensuite un lien vers http://bitbucket.org/birkenfeld/sphinx/issue/123. Comme vous pouvez le constater, la cible donnée dans le rôle est substituée dans l'URL de base à la place de %s.

La légende du lien dépend du deuxième élément du tuple, le préfixe:

Si le préfixe est Aucun, la légende du lien est l'URL complète. Si le préfixe est la chaîne vide, la légende du lien est l'URL partielle indiquée dans le contenu du rôle (123 dans ce cas.) Si le préfixe est une chaîne non vide, la légende du lien est l'URL partielle, précédée du préfixe & # 8211; dans l'exemple ci-dessus, la légende du lien serait issue 123. Vous pouvez également utiliser l'habituel & # 8220; titre explicite & # 8221; syntaxe prise en charge par d'autres rôles générant des liens, c'est-à-dire :issue:`this issue <123>`. Dans ce cas, le préfixe n'est pas pertinent.

Answer 2

Ok, voici comment je l’ai fait. Tout d'abord, apilinks.py (l'extension Sphinx):

from docutils import nodes, utils

def setup(app):
    def api_link_role(role, rawtext, text, lineno, inliner, options={},
                      content=[]):
        ref = app.config.apilinks_base + text
        node = nodes.reference(rawtext, utils.unescape(ref), refuri=ref,
                               **options)
        return [node], []
    app.add_config_value('apilinks_base', 'http://localhost/', False)
    app.add_role('apilink', api_link_role)

Maintenant, dans conf.py, ajoutez 'apilinks' à la liste des extensions et définissez une valeur appropriée pour 'apilinks_base' (sinon, la valeur par défaut sera 'http://localhost/'). Mon fichier ressemble à ceci:

extensions = ['sphinx.ext.autodoc', 'apilinks']
# lots of other stuff
apilinks_base = 'http://host:88/base/'

Utilisation:

:apilink:`path`

Sortie:

<a href="http://host:88/base/path">http://host:88/base/path</a>

Answer 3

J'ai eu un problème similaire dans lequel je devais également remplacer les URL par des cibles d'image. Le extlinks ne pas développer lorsqu'il est utilisé comme valeur d'attribut image :target:. Finalement, j'ai écrit une transformation sphinx personnalisée qui réécrit les URL commençant par un préfixe donné, dans mon cas, http://mybase/. Voici un code pertinent pour conf.py:

from sphinx.transforms import SphinxTransform

class ReplaceMyBase(SphinxTransform):

    default_priority = 750
    prefix = 'http://mybase/'

    def apply(self):
        from docutils.nodes import reference, Text
        baseref = lambda o: (
            isinstance(o, reference) and
            o.get('refuri', '').startswith(self.prefix))
        basetext = lambda o: (
            isinstance(o, Text) and o.startswith(self.prefix))
        base = self.config.mybase.rstrip('/') + '/'
        for node in self.document.traverse(baseref):
            target = node['refuri'].replace(self.prefix, base, 1)
            node.replace_attr('refuri', target)
            for t in node.traverse(basetext):
                t1 = Text(t.replace(self.prefix, base, 1), t.rawsource)
                t.parent.replace(t, t1)
        return

# end of class

def setup(app):
    app.add_config_value('mybase', 'https://en.wikipedia.org/wiki', 'env')
    app.add_transform(ReplaceMyBase)
    return

Ceci étend la première source suivante pour pointer vers wikipedia anglais. Lorsque conf.py définit mybase="https://es.wikipedia.org/wiki", les liens pointent vers le wiki espagnol.

* inline link http://mybase/Helianthus
* `link with text <http://mybase/Helianthus>`_
* `link with separate definition`_
* image link |flowerimage|

.. _link with separate definition: http://mybase/Helianthus

.. |flowerimage| image:: https://upload.wikimedia.org/wikipedia/commons/f/f1/Tournesol.png
   :target: http://mybase/Helianthus

Answer 4

Vous pouvez écrire une extension Sphinx qui crée une rôle comme

:apilink:`path` 

et génère le lien à partir de cela. Je n'ai jamais fait cela, alors je ne peux pas m'empêcher de donner ce pointeur, désolé. Vous devriez essayer de voir comment les différents rôles sont mis en œuvre. Beaucoup sont très similaires à ce dont vous avez besoin, je pense.