Ersetzungen innerhalb von Links in reST/Sphinx

Question

Ich verwende Sphinx um einen Webservice zu dokumentieren, der auf verschiedenen Servern eingesetzt wird. Die Dokumentation enthält zahlreiche URL-Beispiele, auf die der Benutzer klicken kann. Sie sollten einfach funktionieren. Mein Problem ist, dass der Host-, Port- und Deployment-Root variieren und die Dokumentation für jede Bereitstellung neu generiert werden muss.

Ich versuchte Substitutionen wie diese definieren:

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

Aber die erzeugte HTML ist nicht das, was ich will (nicht enthalten "/ path" in der generierten Link):

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

Does weiß jemand wie man das umgeht?

Answer 1

Neu im Sphinx v1.0:

sphinx.ext.extlinks - Markup zu kürzen externe Links

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

Die Erweiterung fügt einen neuen Konfigurationswert:

extlinks

Dieser Konfigurations Wert muss ein Wörterbuch von externen Webseiten sein, die Abbildung einzigartigen kurzen Alias-Namen auf eine Basis-URL und einen Präfix. Zum Beispiel ein Alias ​​für die oben genannten Probleme zu schaffen, würden Sie

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

Jetzt hinzufügen, können Sie den Alias-Namen als eine neue Rolle verwenden, z.B. :issue:`123`. Dies fügt dann eine Verbindung zu http://bitbucket.org/birkenfeld/sphinx/issue/123 ein. Wie Sie sehen können, wird das in der Rolle angegebene Ziel in der Basis-URL anstelle von %s ersetzt.

Der Link Beschriftung auf dem zweiten Element in dem Tupel hängt das Präfix:

Wenn das Präfix None ist, ist der Link caption die vollständige URL. Wenn das Präfix die leere Zeichenfolge ist, ist die Verknüpfungsbeschriftung die im Rolleninhalt angegebene Teil-URL (in diesem Fall 123.) Wenn das Präfix eine nicht leere Zeichenfolge ist, ist die Verknüpfungsbeschriftung die partielle URL, die vom Präfix vorangestellt wird Präfix - im obigen Beispiel wäre die Linkbeschriftung das Problem 123. Sie können auch die übliche "explizite Titel" -Syntax verwenden, die von anderen Rollen unterstützt wird, die Links generieren, zB :issue:`this issue <123>`. In diesem Fall ist das Präfix nicht relevant.

Answer 2

Sie können eine Sphinx schreiben extension, die ein role wie

:apilink:`path` 

erstellt und erzeugt den Link aus, dass. Ich habe das nie gemacht, also kann ich nicht anders, als diesen Zeiger zu geben, tut mir leid. Sie sollten versuchen zu sehen, wie die verschiedenen Rollen implementiert werden. Viele sind dem, was du brauchst, sehr ähnlich, denke ich.

Answer 3

Ok, hier ist, wie ich es gemacht habe. Zuerst apilinks.py (die Sphinx-Erweiterung):

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) 

nun in conf.py, fügen 'apilinks' auf die Erweiterungsliste und legen Sie einen entsprechenden Wert für 'apilinks_base' (sonst wird es zu 'http://localhost/' Standard). Meine Datei sieht wie folgt aus:

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

Verbrauch:

:apilink:`path` 

Ausgang:

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