web-dev-qa-db-fra.com

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

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?

python-sphinxrestructuredtext
86
Sue Walsh

Ignorer cette réponse, cela ne fonctionne pas: meilleure utilisation la réponse de Louis , ci-dessous

Pour l'ancre, vous pouvez définir des noms d'ancres "courts" comme ceci:

.. _ShortAnchor:

Target Header goes here
=======================

Some text.

Pour faire référence à cet en-tête, utilisez:

For more details, see ShortAnchor_.

Notez que cela étend même ShortAnchor au nom complet de l'en-tête.

Vous pouvez aussi utiliser un nom d’en-tête complet comme:

See `Target Header goes here`_ chapter.

Mais ceci est davantage sujet aux erreurs de modification du texte de l'en-tête.

Tout cela fonctionne sur plusieurs fichiers source faisant partie d'une documentation finale.

12
Jan Vlcinsky

L'expression "reST/Sphinx" rend la portée de la question peu claire. S'agit-il de reStructuredText en général et de Sphinx, ou uniquement de reStructuredText tel qu'utilisé dans Sphinx (et non pas reStructuredText en général)? Je vais couvrir les deux, car les personnes utilisant la TVD risquent de rencontrer les deux cas à un moment donné:

Sphinx

Outre les directives spécifiques à un domaine, vous pouvez utiliser des liens vers diverses entités telles que des 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 d'hyperlien général 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 standard reStructuredText vers des sections (comme Section title_) car cela fonctionne entre 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 la 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 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 utilisé. 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 vous voulez que le code HTML final fonctionne dans un navigateur, puis 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 créer un lien vers le fichier HTML final et savoir ce que sera le id donné à la section. Si vous voulez faire la même chose 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 id donné à la section. Toutefois, 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 .

160
Louis

Nouveau, meilleure réponse pour 2016!

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

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


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

alors, 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, c'est qu'il est désormais impossible de dupliquer les titres internes dans la collection de documents. (Ça vaut le coup.)

39
Adam Michael Wood

Exemple:

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

où Homebrew est une section d'un autre document nommé Installation.rst.

Ceci utilise la fonction de sélection automatique , il faudra donc éditer config.py avec ce qui suit:

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