L'ajout d'un renvoi à une sous-position ou d'une ancre d'une autre page

Comment insérer une référence croisée dans un repos/Sphinx page pour un sous-en-tête ou d'une ancre d'une autre page dans le même ensemble de documents?

Double Possible de Comment faire un interne hyper lien en sphinx de documentation

InformationsquelleAutor Sue Walsh | 2013-03-13

python-sphinx restructuredtext

12

Ignorer cette réponse, il ne fonctionne pas: une Meilleure utilisation de la réponse de Louis

Pour point d'ancrage, vous pouvez définir le "court" d'ancrage des noms comme ceci:
```
.. _ShortAnchor:

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

Some text.
```
À se référer à cet en-tête d'utilisation:
```
For more details, see ShortAnchor_.
```
Remarque, que ça se développe ShortAnchor de nom complet de l'en-tête.

Vous pouvez également utiliser pleinement le nom d'en-tête comme:
```
See `Target Header goes here`_ chapter.
```
Mais ce n'est plus d'erreur sujettes à modification de texte d'en-tête.

Tout cela fonctionne à travers de multiples fichiers source faisant partie de la documentation finale.
- Cela n'a pas fonctionné pour moi, lorsque l'ancre, je voulais consultez était dans un autre document, au lieu de cela, j'ai trouvé que l'utilisation d' :ref: fonctionné bien (voir: sphinx.pocoo.org/markup/...)
- J'ai trouvé, ma réponse n'a pas vraiment de travail. S'il vous plaît, choisissez/accepter le meilleur (par exemple, par Louis, qui fonctionne pour moi), de sorte que je peux supprimer mon confuse.
InformationsquelleAutor Jan Vlcinsky
153

L'expression "repos/Sphinx" met à la portée de la question pas claire. Est-ce reStructuredText en général et Sphinx, ou seulement sur reStructuredText utilisé dans Sphinx (et pas reStructuredText en général)? Je vais à couvrir à la fois, car les gens à l'aide de la TVD sont susceptibles de courir dans les deux cas à un certain point:

Sphinx

Outre le domaine des directives spécifiques qui peuvent être utilisés pour lier les diverses entités telles que les classes (:class:) il y a le général :ref: directive, documenté 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 général de liens hypertexte mécanisme offert par la TVD ne travail que dans le Sphinx, la documentation recommande à l'encontre de l'aide lors de l'utilisation de Sphinx:

À l'aide de ref est conseillé sur la norme de reStructuredText liens vers des sections (comme Section title_), car il fonctionne sur les fichiers, lorsque les titres de sections sont modifiés, et pour tous les constructeurs qui prennent en charge de références croisées.

PREMIER, en Général

Les outils convertir TVD fichiers au format HTML n'ont pas nécessairement une notion de collection. C'est le cas, par exemple, si vous comptez sur github pour convertir TVD fichiers au format 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é varier selon l'outil que vous utilisez. Par exemple, si vous utilisez rst2html et vous voulez que les fichiers A.rst de lien vers une section nommée "Section" dans le fichier other.rst et vous souhaitez le HTML final de travailler dans un navigateur, puis A.rst contient:
```
`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 avez un lien pour le dernier fichier HTML et vous devez savoir ce que le id donnée à la section sera. Si vous voulez faire de même 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 avez besoin de savoir l' id donnée à la section. Cependant, vous avez un lien pour le premier fichier, car c'est seulement lors de l'accès le premier fichier HTML est créé. (Au moment de la rédaction de cette réponse, en accédant directement du code HTML n'est pas autorisé.)

Un exemple complet est disponible ici.
- Bien meilleure réponse que celle acceptée par la question de propriétaire. (Malgré le fait que RST, in General, a été décevant nouvelles!)
- Un inconvénient du Sphinx .. _my-reference-label: approche est que my-reference-label est indiqué dans l'URL après # dans le lien. Donc, on doit utiliser de jolis noms d'étiquettes. Aussi, la table des matières crée toujours un #-lien de Section to cross-reference, et donc on se retrouve avec deux différents #-des liens vers la même section.
InformationsquelleAutor Louis
37

Nouveau, de meilleure réponse pour 2016!

La autosection extension vous permet de faire cela facilement.
```
=============
Some Document
=============


Internal Headline
=================
```
puis, plus tard...
```
===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`
```
Cette extension est intégrée, de sorte que tous vous avez besoin est de modifier conf.py
```
extensions = [
    .
    . other
    . extensions
    . already
    . listed
    .
    'sphinx.ext.autosectionlabel',
]
```
La seule chose que vous devez faire attention est que maintenant vous ne pouvez pas dupliquer interne les gros titres dans la doc de la collection. (La peine.)
- Depuis que j'ai écrit cette réponse, j'ai découvert, dans la pratique, deux problèmes avec cette approche. Tout d'abord, la section de renommage est un problème. Deuxièmement, vous avez souvent courte section des titres comme "en Savoir plus" ou "aperçu" que vous souhaitez utiliser, vous ne pouvez pas si vous faites cela. Solution: ajouter le titre de la section lorsque/si vous renommez; ajouter un titre de section pour le court titres de section (comme _page-title-learn-more). C'est un peu ennuyeux, mais j'aime toujours principalement en s'appuyant sur autosection.
- Sphinx 1.6 présente le autosectionlabel_prefix_document option de configuration qui permet d'éviter une double manchette question en préfixant chaque section de l'étiquette avec le nom du document, il vient de.
InformationsquelleAutor Adam Michael Wood
2

Exemple:
```
Hey, read the :ref:`Installation:Homebrew` section.
```
où Homebrew est une section à l'intérieur d'un autre document nommé Installation.rst.

Il utilise le autosection fonctionnalité, et aura donc besoin de modifier config.py avec les éléments suivants:
```
extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
```
InformationsquelleAutor Jano

Vous devez vous connecter pour publier un commentaire.

Sphinx

PREMIER, en Général