Aggiunta di un riferimento incrociato a un sottotitolo o ancora in un'altra pagina

Question

Come inserire un riferimento incrociato in una pagina reST/Sfinge su un'intestazione secondaria o su un'ancora in un'altra pagina nello stesso set di documentazione?

Answer 1

Ignorare questa risposta, non funziona: un uso migliore la risposta da Louis

per l'ancora, è possibile definire i nomi di ancoraggio "corte" in questo modo:

.. _ShortAnchor: 

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

Some text. 

fare riferimento a tale uso intestazione:

For more details, see ShortAnchor_. 

Nota, che questo espande anche ShortAnchor al nome completo dell'intestazione.

Si può anche utilizzare il nome completo di intestazione come:

See `Target Header goes here`_ chapter. 

ma questo è più soggetto a errori di modifiche di testo dell'intestazione.

Tutto questo funziona su più file sorgente che fanno parte di una documentazione finale.

Answer 2

L'espressione "reST/Sphinx" rende poco chiara la portata della domanda. Riguarda reStructuredText in generale e Sfinge, oppure solo su reStructuredText come utilizzato in Sfinge (e non in ReStructuredText in generale)? Sto andando a coprire sia in quanto persone che utilizzano RST sono probabilità di incorrere in entrambi i casi a un certo punto:

Sfinge

Oltre alle direttive specifiche del dominio che possono essere utilizzati per creare un collegamento a diverse entità come le classi (:class:) c'è la direttiva generale :ref:, documentata here. 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 collegamenti ipertestuali generale offerto dalla RST funziona nella Sfinge, la documentazione raccomanda di non usarlo quando si utilizza Sfinge:

Utilizzando ref è consigliato su link reStructuredText standard alle sezioni (come Section title _) perché funziona su tutti i file, quando le intestazioni delle sezioni sono cambiate e per tutti i costruttori che supportano riferimenti incrociati.

RST, in generale

Gli strumenti che convertono file RST in HTML non hanno necessariamente una nozione di raccolta. Questo è il caso ad esempio se ci si basa su github per convertire i file RST in HTML o se si utilizza 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 si sta utilizzando.Per esempio, se si utilizza rst2html e si desidera archiviare A.rst collegare a una sezione chiamata "sezione" nel file other.rst e si desidera che la finale HTML di lavorare in un browser, quindi A.rst conterrebbe:

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

Hai per collegarsi al file HTML finale e devi sapere che cosa sarà la id assegnata alla sezione. Se si vuole fare lo stesso per un file servito attraverso 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 id dato alla sezione. Tuttavia, si collega al file RST poiché solo quando si accede al file RST viene creato l'HTML. (Al momento della stesura di questa risposta, l'accesso diretto all'HTML non è consentito.)

Un esempio completo è disponibile here.

Answer 3

Nuova, migliore risposta per il 2016!

Il autosection extension consente di farlo facilmente.

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


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

poi, più tardi ...

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


A link- :ref:`Internal Headline` 

Questa estensione è built-in, quindi tutto ciò che serve è modificare conf.py

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

L'unica cosa che dovete stare attenti di questo è che ora non è possibile duplicare i titoli interni nella raccolta di documenti. (Vale la pena.)