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

Question

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

Answer 1

L'expression "reST/Sphinx" rend la portée de la question peu claire. S'agit-il de reStructuredText en général ? et Sphinx, ou seulement à propos de reStructuredText dans le cadre de Sphinx (et non reStructuredText en général) ? Je vais couvrir les deux puisque les personnes qui utilisent 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 établir des liens avec diverses entités comme les classes ( :class: ) il y a le général :ref: directive, 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'hyperlien offert par RST fonctionne dans Sphinx, la documentation recommande de ne pas l'utiliser lorsque vous utilisez Sphinx :

L'utilisation de ref est conseillée par rapport aux liens standards de reStructuredText vers les sections (comme Section title _) parce qu'il fonctionne dans tous les fichiers, lorsque les titres de section sont modifiés, et pour tous les constructeurs qui prennent 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 la notion de collection . C'est le cas par exemple si vous comptez sur github pour convertir les fichiers RST en HTML ou si vous utilisez un outil en 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 rst2html et vous voulez le fichier A.rst pour créer un lien vers une section nommée "Section" dans le fichier other.rst et que vous voulez que le HTML final fonctionne dans un navigateur, alors A.rst contiendrait :

`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 faire un lien vers le fichier HTML final et vous devez savoir ce que le id donné à la section sera. Si vous voulez faire la même chose pour un fichier servi par 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 id donné à la section. Cependant, vous créez un lien vers le fichier RST car c'est seulement en accédant au fichier RST que le 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 .

Answer 2

Une nouvelle et meilleure réponse pour 2016 !

El extension de l'autosection 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 maintenant vous ne pouvez pas dupliquer les titres internes dans la collection de documents. (Cela en vaut la peine.)

Answer 3

Exemple :

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

donde Homebrew est une section à l'intérieur d'un document différent nommé Installation.rst .

Cela utilise le fonction d'autosection Il faudra donc modifier config.py avec les éléments suivants :

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True

Answer 4

Dans Sphinx 3.0.3, la seule solution qui a fonctionné pour moi est la suivante :any: (voir https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-anything ). Supposons qu'un document comporte une telle section :

... _my-section:

My Section
----------

Lorem ipsum blablabla

Ensuite, un autre document peut avoir le fragment suivant pour créer un lien :

See :any:`my-section` for the details

Answer 5

Ajout de la description d'un comportement qui était déroutant pour moi.

Les titres des sections doivent être référencés en faisant précéder le nom du fichier (aperçu ici) :

aperçu.rst :

    ************
    API Overview
    ************

index.rst :

    :ref:`overview:API Overview`

Cependant, lors de la référence à des liens, le nom du fichier (constantes ici) ne doit pas être présent :

constants.rst :

    .. _section-constants:

    *******************
    Enums and Constants
    *******************

api.rst :

    :ref:`section-constants`

De plus, pour que cela fonctionne, il faut activer l'extension 'autosectionlabel' :

conf.py :

    extensions = [
        ...
        "sphinx.ext.autosectionlabel"
    ]