Hinzufügen eines Querverweises zu einer Unterüberschrift oder einem Anker auf einer anderen Seite

110

Wie füge ich einen Querverweis in eine reST / Sphinx-Seite ein, entweder in einen Unterheader oder in einen Anker auf einer anderen Seite im selben Dokumentationssatz?

Sue Walsh
quelle
Mögliches Duplikat von Wie man einen internen
Hyperlink

Antworten:

207

Der Ausdruck "reST / Sphinx" macht den Umfang der Frage unklar. Geht es um reStructuredText im Allgemeinen und Sphinx oder nur um reStructuredText, wie in Sphinx verwendet wird (und nicht um reStructuredText im Allgemeinen)? Ich werde beide behandeln, da Menschen, die RST verwenden, wahrscheinlich irgendwann auf beide Fälle stoßen:

Sphinx

Neben den domänenspezifischen Anweisungen, die zum Verknüpfen mit verschiedenen Entitäten wie classes ( :class:) verwendet werden können, gibt es die hier:ref: dokumentierte allgemeine Anweisung . Sie geben dieses Beispiel:

    .. _my-reference-label:

    Section to cross-reference
    --------------------------

    This is the text of the section.

    It refers to the section itself, see :ref:`my-reference-label`.

Obwohl der von RST angebotene allgemeine Hyperlinking-Mechanismus in Sphinx funktioniert, wird in der Dokumentation davon abgeraten, ihn bei Verwendung von Sphinx zu verwenden:

Die Verwendung von ref wird über Standard-reStructuredText-Links zu Abschnitten (wie Section title_) empfohlen, da dies dateiübergreifend funktioniert, wenn Abschnittsüberschriften geändert werden, und für alle Builder, die Querverweise unterstützen.

RST im Allgemeinen

Die Tools, die RST-Dateien in HTML konvertieren, müssen nicht unbedingt eine Sammlung enthalten . Dies ist beispielsweise der Fall, wenn Sie sich beim Konvertieren von RST-Dateien in HTML auf github verlassen oder wenn Sie ein Befehlszeilenprogramm wie verwenden rst2html. Leider variieren die verschiedenen Methoden, um das gewünschte Ergebnis zu erzielen, je nachdem, welches Tool Sie verwenden. Wenn Sie beispielsweise verwenden rst2htmlund möchten, dass die Datei A.rstmit einem Abschnitt mit dem Namen "Abschnitt" in der Datei verknüpft wird other.rstund der endgültige HTML-Code in einem Browser funktioniert, A.rstenthält er Folgendes:

`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.

Sie müssen auf die endgültige HTML-Datei verlinken und wissen id, wie der Abschnitt aussehen wird. Wenn Sie dasselbe für eine Datei tun möchten, die über github bereitgestellt wird:

`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.

Auch hier müssen Sie die idAngaben zum Abschnitt kennen. Sie verknüpfen jedoch die RST-Datei, da der HTML-Code erst beim Zugriff auf die RST-Datei erstellt wird. (Zum Zeitpunkt des Schreibens dieser Antwort ist der direkte Zugriff auf HTML nicht zulässig.)

Ein vollständiges Beispiel finden Sie hier .

Louis
quelle
9
Viel bessere Antwort als die vom Frageninhaber akzeptierte. (Trotz der Tatsache, dass RST, in Generalenttäuschende Nachrichten!)
dlm
1
Ein Nachteil des Sphinx- .. _my-reference-label:Ansatzes besteht darin, dass my-reference-labeler in der URL nach #dem Link angezeigt wird . Man muss also hübsche Markennamen verwenden. Außerdem erstellt das Inhaltsverzeichnis immer einen #Link zu Section to cross-referenceund somit #erhält man zwei verschiedene Links zu demselben Abschnitt.
st12
3
Und wenn Sie Ihrem Link einen anderen Namen geben möchten, können Sie ihn jederzeit verwenden:ref:`Link title <lmy-reference-label>`
HyperActive
52

Neue, bessere Antwort für 2016!

Mit der Autosection-Erweiterung können Sie dies ganz einfach tun.

=============
Some Document
=============


Internal Headline
=================

dann später...

===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`

Diese Erweiterung ist integriert. Sie müssen sie also nur bearbeiten conf.py

extensions = [
    .
    . other
    . extensions
    . already
    . listed
    .
    'sphinx.ext.autosectionlabel',
]

Das einzige, worauf Sie achten müssen, ist, dass Sie jetzt keine internen Überschriften in der gesamten Dokumentensammlung duplizieren können. (Es ist es wert.)

Adam Michael Wood
quelle
5
Seit ich diese Antwort geschrieben habe, habe ich in der Praxis einige Probleme mit diesem Ansatz entdeckt. Erstens ist das Umbenennen von Abschnitten ein Problem. Zweitens haben Sie häufig kurze Abschnittsüberschriften wie "Weitere Informationen" oder "Übersicht", die Sie verwenden möchten, was Sie in diesem Fall nicht können. Lösung: Fügen Sie den Abschnittstitel hinzu, wenn Sie ihn umbenennen. Fügen Sie einen Abschnittstitel für die kurzen Abschnittstitel hinzu (wie _page-title-learn-more). Es ist ein bisschen nervig, aber ich mag es immer noch, mich hauptsächlich auf die Autosection zu verlassen.
Adam Michael Wood
12
Sphinx 1.6 führt die autosectionlabel_prefix_documentKonfigurationsoption ein, mit der Sie das Problem doppelter Überschriften vermeiden können, indem Sie jeder Abschnittsbezeichnung den Namen des Dokuments voranstellen, aus dem es stammt.
pmos
2
Dies ist die beste Lösung. Und der Link-Titel kann leicht mit geändert werden :ref:`Link title <Internal Headline>`. Sie können auch mit:doc:`quickstart`
HyperActive
5

Beispiel:

Hey, read the :ref:`Installation:Homebrew` section.

Wo Homebrewist ein Abschnitt in einem anderen Dokument mit dem Namen Installation.rst.

Dies verwendet die automatische Schnittfunktion und muss daher wie folgt bearbeitet werden config.py:

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
Jano
quelle
In 2.0.0b1 wurde hinzugefügt autosectionlabel_maxdepth, sodass Sie diese Variable auf> = setzen müssen, damit das Autosectionlabel funktioniert 2. Wenn Dokumente wie in Unterverzeichnissen generiert werden html, müssen Sie refs den Namen voranstellen : :ref:'html/Installation:Homebrew'. Aus diesem Grund möchten Sie möglicherweise einen generischen Verzeichnisnamen auswählen generated, um Refs weniger seltsam aussehen zu lassen, wenn sie mit anderen Formaten als HTML verwendet werden. Aus diesem Grund können Sie auch 'Homebrew <Installation.html#Homebrew>'__das richtige reST verwenden und nicht an Sphinx gebunden sein.
Pugsley
Ich brauchte das html/Präfix nicht
Chris