Ersetzungen innerhalb von Links in reST / Sphinx

Question

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?

Answer 1

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.

Answer 2

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>

Answer 3

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

Answer 4

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.