sphinx.ext.extlinks – Markup to shorten external links

Module author: Georg Brandl

Hinzugefügt in Version 1.0.

Diese Erweiterung soll mit dem gängigen Muster helfen, viele externe Links zu haben, die auf URLs derselben Seite zeigen, z. B. Links zu Bugtrackern, Web-Interfaces für Versionskontrollsysteme oder einfach Unterseiten auf anderen Websites. Dies geschieht durch die Bereitstellung von Aliassen für Basis-URLs, sodass Sie nur den Namen der Unterseite angeben müssen, wenn Sie einen Link erstellen.

Nehmen wir an, Sie möchten viele Links zu Problemen im Sphinx-Tracker einfügen, unter https://github.com/sphinx-doc/sphinx/issues/num. Das wiederholte Tippen dieser URL ist mühsam, daher können Sie extlinks verwenden, um Wiederholungen zu vermeiden.

Die Erweiterung fügt einen Konfigurationswert hinzu

extlinks

Typ:

dict[str, tuple[str, str | None]]

Standard:

{}

Dieser Konfigurationswert muss ein Wörterbuch externer Sites sein, das eindeutige kurze Aliasnamen einer *Basis-URL* und einer *Beschriftung* zuordnet. Um beispielsweise einen Alias für die oben genannten Probleme zu erstellen, würden Sie Folgendes hinzufügen

extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
                      'issue %s')}

Jetzt können Sie den Aliasnamen als neue Rolle verwenden, z. B. :issue:`123`. Dies fügt dann einen Link zu https://github.com/sphinx-doc/sphinx/issues/123 ein. Wie Sie sehen können, wird das in der Rolle angegebene Ziel in der *Basis-URL* anstelle von %s eingefügt.

Die Link-Beschriftung hängt vom zweiten Element des Tupels ab, der *Beschriftung*

• Wenn *caption* None ist, ist die Link-Beschriftung die vollständige URL.

• Wenn *caption* ein String ist, muss dieser genau einmal %s enthalten. In diesem Fall ist die Link-Beschriftung *caption*, wobei der Teil-URL für %s eingefügt wird – im obigen Beispiel wäre die Link-Beschriftung issue 123.

Um ein literales % sowohl in der *Basis-URL* als auch in der *Beschriftung* zu erzeugen, verwenden Sie %%

extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
                      '[K&R; page %s]')}

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 die *Beschriftung* nicht relevant.

Geändert in Version 4.0: Unterstützung für die Ersetzung durch '%s' in der Beschriftung.

Hinweis

Da Links im Lesezustand aus der Rolle generiert werden, erscheinen sie als normale Links für z. B. den linkcheck-Builder.

extlinks_detect_hardcoded_links

Typ:

bool

Standard:

False

Wenn aktiviert, gibt extlinks eine Warnung aus, wenn ein hartcodierter Link durch einen extlink ersetzbar ist, und schlägt eine Ersetzung per Warnung vor.

Hinzugefügt in Version 4.5.

Vorherige

sphinx.ext.duration – Messen der Dauer von Sphinx-Verarbeitung

Nächste

sphinx.ext.githubpages – Veröffentlichen von HTML-Dokumenten in GitHub Pages