Antworten:
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:
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.
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 .
RST, in Generalenttäuschende Nachrichten!)
.. _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.
:ref:`Link title <lmy-reference-label>`
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.)
_page-title-learn-more). Es ist ein bisschen nervig, aber ich mag es immer noch, mich hauptsächlich auf die Autosection zu verlassen.
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.
:ref:`Link title <Internal Headline>`. Sie können auch mit:doc:`quickstart`
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
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.
html/Präfix nicht