Substitutions dans les liens dans reST/Sphinx

Question

J'utilise Sphinx pour documenter un service Web qui sera déployé sur différents serveurs. La documentation est remplie d'exemples d'URL que l'utilisateur doit cliquer et ils devraient simplement fonctionner. Mon problème est que l'hôte, le port et la racine de déploiement varient et la documentation devra être re-générée pour 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é est pas ce que je veux (ne comprend pas "/ path" dans le lien généré):

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

Est-ce quelqu'un sait comment contourner cela?

Answer 1

Nouveau dans v1.0 Sphinx:

sphinx.ext.extlinks - Marquage à raccourcir les liens externes

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

L'extension ajoute une nouvelle valeur de configuration:

extlinks

Cette valeur de configuration doit être un dictionnaire des sites externes, la cartographie des noms d'alias unique court à une URL de base et un préfixe. Par exemple, pour créer un alias pour les problèmes mentionnés ci-dessus, vous ajouteriez

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

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

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

Si le préfixe est Aucun, la légende de lien est l'URL complète. Si le préfixe est la chaîne vide, la légende de lien est l'URL partielle donnée dans le contenu du rôle (123 dans ce cas.) Si le préfixe est une chaîne non vide, la légende de lien est l'URL partielle, précédée du préfixe - dans l'exemple ci-dessus, la légende de lien serait le numéro 123. Vous pouvez également utiliser la syntaxe habituelle de "titre explicite" supportée par d'autres rôles qui génèrent des liens, par exemple :issue:`this issue <123>`. Dans ce cas, le préfixe n'est pas pertinent.

Answer 2

Vous pouvez écrire un Sphinx extension qui crée un role comme

:apilink:`path` 

et génère le lien de cela. Je n'ai jamais fait cela, donc je ne peux pas aider plus que de donner ce pointeur, désolé. Vous devriez essayer de voir comment les différents rôles sont implémentés. Beaucoup sont très semblables à ce dont vous avez besoin, je pense.

Answer 3

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, en conf.py, ajouter 'apilinks' à la liste des extensions et définir une valeur appropriée pour 'apilinks_base' (sinon, il sera par défaut '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>