Comment insérer une référence croisée dans une page reST / Sphinx vers un sous-en-tête ou une ancre dans une autre page du même ensemble de documentation?

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 .

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

Exemple:

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

où 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