Ersetzungen innerhalb von Links in reST / Sphinx
-
22-07-2019 - |
Frage
Ich verwende Sphinx, um einen Webservice zu dokumentieren, der auf verschiedenen Servern bereitgestellt wird.Die Dokumentation ist voll von URL-Beispielen, auf die der Benutzer klicken kann, und sie sollten einfach funktionieren.Mein Problem ist, dass Host, Port und Bereitstellungsstamm variieren und die Dokumentation für jede Bereitstellung neu generiert werden muss.
Ich habe versucht, Ersetzungen wie folgt zu definieren:
|base_url|/path
.. |base_url| replace:: http://localhost:8080
Aber der generierte HTML-Code ist nicht das, was ich will (enthält „/path“ nicht im generierten Link):
<a href="http://localhost:8080">http://localhost:8080</a>/path
Weiß jemand, wie man das umgehen kann?
Lösung
Neu in Sphinx v1.0:
sphinx.ext.extlinks – Markup zum Kürzen externer Links
http://sphinx.pocoo.org/ext/extlinks.html
Die Erweiterung fügt einen neuen Konfigurationswert hinzu:
Extlinks
Dieser Konfigurationswert muss ein Wörterbuch externer Websites sein, das eindeutige kurze Aliasnamen einer Basis-URL und einem Präfix zuordnet.Um beispielsweise einen Alias für die oben genannten Probleme zu erstellen, würden Sie hinzufügen
extlinks = {'issue':
('http://bitbucket.org/birkenfeld/sphinx/issue/%s', 'issue ')}
Jetzt können Sie den Aliasnamen als neue Rolle verwenden, z.B. :issue:`123`
.Dadurch wird dann ein Link zu eingefügt http://bitbucket.org/birkenfeld/sphinx/issue/123.Wie Sie sehen können, wird das in der Rolle angegebene Ziel in der Basis-URL anstelle von ersetzt %s
.
Die Linkbeschriftung hängt vom zweiten Element im Tupel ab, dem Präfix:
Wenn das Präfix „None“ lautet, ist die Linkbeschriftung die vollständige URL.Wenn das Präfix die leere Zeichenfolge ist, ist die Link-Bildunterschrift die partielle URL, die im Rolleninhalt (123 in diesem Fall) angegeben ist. Im obigen Beispiel wäre die Verknüpfungsunterschrift Ausgabe 123.Sie können auch die übliche „explizite Titel“-Syntax verwenden, die von anderen Rollen unterstützt wird, die Links generieren, d. h. :issue:`this issue <123>`
.In diesem Fall ist das Präfix nicht relevant.
Andere Tipps
Ok, hier ist, wie ich es tat. 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 '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`
Ausgabe:
<a href="http://host:88/base/path">http://host:88/base/path</a>
Ich hatte ein ähnliches Problem, wo ich brauchte auch URLs in Bild Zielen zu ersetzen.
Die extlinks
nicht erweitern, wenn sie als Wert des Bildes :target:
Attribut verwendet.
Schließlich schrieb ich eine benutzerdefinierten Sphinx Transformation, die URLs, die mit einem bestimmten Präfix beginnen, in meinem Fall umschreibt, http://mybase/
. Hier ist eine entsprechende Code für 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
Dies erweitert die folgende erste Quelle auf Englisch wikipedia zu zeigen.
Wenn conf.py Sets mybase="https://es.wikipedia.org/wiki"
die Links zu dem spanischen Wiki verweisen würden.
* 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
können Sie schreiben eine Sphinx Erweiterung dass eine Rolle wie
:apilink:`path`
und erzeugt den Link aus, dass. Ich habe noch nie so, so kann ich nicht mehr helfen, als dieser Zeiger geben, sorry. Sie sollten versuchen, wie sich die verschiedenen Rollen implementiert sind zu suchen. Viele sind sehr ähnlich, was Sie brauchen, denke ich.