Come inserire un riferimento incrociato in una pagina reST / Sphinx a un'intestazione secondaria o un ancoraggio in un'altra pagina nello stesso set di documentazione?

L'espressione "reST / Sphinx" rende poco chiaro lo scopo della domanda. Riguarda reStructuredText in generale e Sphinx, o solo reStructuredText come usato in Sphinx (e non reStructuredText in generale)? Coprirò entrambi poiché è probabile che le persone che utilizzano RST si imbattano in entrambi i casi ad un certo punto:

Sfinge

Oltre alle direttive specifiche del dominio che possono essere utilizzate per collegarsi a varie entità come classes ( :class:), c'è la :ref:direttiva generale , documentata qui . Danno questo esempio:

    .. _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`.

Sebbene il meccanismo di collegamento ipertestuale generale offerto da RST funzioni in Sphinx, la documentazione sconsiglia di utilizzarlo quando si utilizza Sphinx:

L'uso di ref è consigliato rispetto ai link reStructuredText standard alle sezioni (come Section title_) perché funziona su tutti i file, quando le intestazioni delle sezioni vengono modificate e per tutti i builder che supportano i riferimenti incrociati.

RST, in generale

Gli strumenti che convertono i file RST in HTML non hanno necessariamente una nozione di raccolta . Questo è il caso, ad esempio, se ti affidi a github per convertire i file RST in HTML o se usi uno strumento da riga di comando come rst2html. Sfortunatamente, i vari metodi da utilizzare per ottenere il risultato desiderato variano a seconda dello strumento che stai utilizzando. Ad esempio, se utilizzi rst2htmle desideri che il file si A.rstcolleghi a una sezione denominata "Sezione" nel file other.rste desideri che l'HTML finale funzioni in un browser, allora A.rstconterrà:

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

Devi collegarti al file HTML finale e devi sapere quale sarà il iddato alla sezione. Se vuoi fare lo stesso per un file servito tramite 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``.

Anche qui è necessario conoscere il iddato alla sezione. Tuttavia, ci si collega al file RST perché è solo all'accesso al file RST che viene creato l'HTML. (Al momento della stesura di questa risposta, l'accesso diretto all'HTML non è consentito.)

Un esempio completo è disponibile qui .

Nuova, migliore risposta per il 2016!

L' estensione di autosection ti consente di farlo facilmente.

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


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

poi più tardi...

===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`

Questa estensione è integrata, quindi tutto ciò di cui hai bisogno è modificare conf.py

extensions = [
    .
    . other
    . extensions
    . already
    . listed
    .
    'sphinx.ext.autosectionlabel',
]

L'unica cosa a cui devi stare attento è che ora non puoi duplicare i titoli interni nella raccolta di documenti. (Ne e 'valsa la pena.)

Esempio:

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

dove si Homebrewtrova una sezione all'interno di un documento diverso denominato Installation.rst.

Questo utilizza la funzione di selezione automatica , quindi sarà necessario modificare config.pycon quanto segue:

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