Réponses:
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é:
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.
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 rst2html
et que vous souhaitez que le fichier soit A.rst
lié à une section nommée «Section» dans le fichier other.rst
et que vous souhaitez que le HTML final fonctionne dans un navigateur, il A.rst
contiendra:
`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 id
donné à 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 id
contenu 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 .
RST, in General
, était une nouvelle décevante!)
.. _my-reference-label:
approche Sphinx est qu'elle my-reference-label
est 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.
:ref:`Link title <lmy-reference-label>`
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.)
_page-title-learn-more
). C'est un peu ennuyeux, mais j'aime toujours me fier à l'autosection.
autosectionlabel_prefix_document
option 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.
:ref:`Link title <Internal Headline>`
. De plus, vous pouvez créer un lien direct vers une page (quickstart.rst par exemple) avec:doc:`quickstart`
Exemple:
Hey, read the :ref:`Installation:Homebrew` section.
où Homebrew
est 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.py
les éléments suivants:
extensions = [
'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
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.
html/
préfixe