Ajouter une référence croisée à un sous-titre ou une ancre dans une autre page

Réponses:

207

L'expression «reST / Sphinx» rend la portée de la question floue. S'agit-il de reStructuredText en général et de Sphinx, ou uniquement de reStructuredText tel qu'il est utilisé dans Sphinx (et non de reStructuredText en général)? Je vais couvrir les deux car les personnes utilisant RST sont susceptibles de rencontrer les deux cas à un moment donné:

Sphinx

Outre les directives spécifiques au domaine qui peuvent être utilisées pour se lier à diverses entités telles que classes ( :class:), il y a la :ref:directive générale , documentée ici . Ils donnent cet exemple:

    .. _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`.

Bien que le mécanisme général d'hyperliens proposé par RST fonctionne dans Sphinx, la documentation recommande de ne pas l'utiliser lors de l'utilisation de Sphinx:

L'utilisation de ref est conseillée par rapport aux liens reStructuredText standard vers des sections (comme Section title_) car cela fonctionne sur plusieurs fichiers, lorsque les en-têtes de section sont modifiés et pour tous les générateurs prenant en charge les références croisées.

RST, en général

Les outils qui convertissent les fichiers RST en HTML n'ont pas nécessairement une notion de collection . C'est le cas par exemple si vous comptez sur github pour convertir des fichiers RST en HTML ou si vous utilisez un outil de ligne de commande comme rst2html. Malheureusement, les différentes méthodes à utiliser pour obtenir le résultat souhaité varient en fonction de l'outil que vous utilisez. Par exemple, si vous utilisez rst2htmlet que vous souhaitez que le fichier soit A.rstlié à une section nommée «Section» dans le fichier other.rstet que vous souhaitez que le HTML final fonctionne dans un navigateur, il A.rstcontiendra:

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

Vous devez créer un lien vers le fichier HTML final et vous devez savoir ce que sera iddonné à la section. Si vous souhaitez faire de même pour un fichier servi via github:

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

Ici aussi, vous devez connaître le idcontenu de la section. Cependant, vous créez un lien vers le fichier RST car c'est uniquement lors de l'accès au fichier RST que le code HTML est créé. (Au moment de la rédaction de cette réponse, l'accès direct au HTML n'est pas autorisé.)

Un exemple complet est disponible ici .

Louis
la source
9
Bien meilleure réponse que celle acceptée par le propriétaire de la question. (Malgré le fait que RST, in General, était une nouvelle décevante!)
dlm
1
Un inconvénient de l' .. _my-reference-label:approche Sphinx est qu'elle my-reference-labelest affichée dans l'URL après #dans le lien. Il faut donc utiliser de jolis noms d'étiquettes. De plus, la table des #matières crée toujours un -lien vers Section to cross-reference, et donc on se retrouve avec deux #-liens différents vers la même section.
st12
4
Et si vous voulez donner à votre lien un nom différent, vous pouvez toujours utiliser:ref:`Link title <lmy-reference-label>`
HyperActive
53

Nouvelle, meilleure réponse pour 2016!

L' extension de sélection automatique vous permet de le faire facilement.

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


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

puis, plus tard ...

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


A link-  :ref:`Internal Headline`

Cette extension est intégrée, il vous suffit donc de modifier conf.py

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

La seule chose à laquelle vous devez faire attention est que vous ne pouvez plus dupliquer les titres internes dans la collection de documents. (Ça vaut le coup.)

Adam Michael Wood
la source
5
Depuis que j'ai écrit cette réponse, j'ai découvert dans la pratique quelques problèmes avec cette approche. Premièrement, le changement de nom de section est un problème. Deuxièmement, vous avez souvent de courts titres de sections comme "En savoir plus" ou "Vue d'ensemble" que vous souhaitez utiliser, ce que vous ne pouvez pas faire si vous le faites. Solution: ajoutez le titre de la section lorsque / si vous renommez; ajoutez un titre de section pour les titres de section courte (comme _page-title-learn-more). C'est un peu ennuyeux, mais j'aime toujours me fier à l'autosection.
Adam Michael Wood
12
Sphinx 1.6 introduit l' autosectionlabel_prefix_documentoption de configuration qui vous permet d'éviter le problème de doublon de titre en préfixant chaque étiquette de section avec le nom du document dont elle provient.
pmos
2
C'est la meilleure solution. Et le titre du lien peut être facilement modifié avec :ref:`Link title <Internal Headline>`. De plus, vous pouvez créer un lien direct vers une page (quickstart.rst par exemple) avec:doc:`quickstart`
HyperActive
5

Exemple:

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

Homebrewest une section à l'intérieur d'un autre document nommé Installation.rst.

Cela utilise la fonction de sélection automatique , vous devrez donc modifier config.pyles éléments suivants:

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
Jano
la source
Dans 2.0.0b1, ils ont ajouté autosectionlabel_maxdepth, donc pour que l'autosectionlabel fonctionne, vous devez définir cette variable sur> = 2. En outre, si docs sont générés à subdir, comme html, vous devez ajouter un préfixe refs avec son nom: :ref:'html/Installation:Homebrew'. Pour cette raison, vous pouvez choisir un nom de répertoire générique, comme generated, pour rendre les références moins bizarres lorsqu'elles sont utilisées avec des formats autres que HTML. Pour cette raison, vous pourriez aussi bien 'Homebrew <Installation.html#Homebrew>'__utiliser la reST appropriée et ne pas être lié à Sphinx.
Pugsley
Je n'ai pas besoin du html/préfixe
Chris