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?

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 .

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.)

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