Navegant per l'interior de la documentació creada per Sphinx

En aquest article veurem algunes de les possibilitats que ofereix el llenguatge de marques RST  i Sphinx per generar enllaços i dreceres a l'interior de la documentació que crea.

Referències internes

Una referència interna ens remet a un altre punt de la documentació on es tracta el tema del que estem parlant. La solució més habitual és un text del tipus: Tal com es pot veure a la Secció... o bé Trobareu més informació a ... En tots els casos apareix un hiperenllaç que quan cliquem a sobre ens porta a l'altre punt del document.

Per aconseguir-ho primer hem de marcar la secció-objectiu on apuntarà l'enllaç amb una etiqueta amb aquesta sintaxi:

.. _NomEtiqueta:

Títol de la secció
---------------------
Ara ja podem anar al punt on volem posar la referència i escriure, per exemple: Trobareu més informació a :ref:`NomEtiqueta`
Quan processem amb Sphinx aquest codi generarà l'enllaç de manera que podrem clicar i anar a l'objectiu on apunta la referència (la secció Cos en aquest exemple):

Generar l'índex

La Taula de continguts d'un document es genera automàticament a partir de les seccions de cada capítol o bé marcant-les manualment amb la directiva toctree, tal com vam veure a l'anterior entrada Estructura dels documents amb Sphinx.

Però l'Índex es genera automàticament a partir de les entrades que marquem manualment perquè hi surtin. Per això cal que, a mesura que anem escrivint el text i vulguem que una paraula aparegui a l'índex, la marquem amb aquesta sintaxi: 
:index:`paraulaperl'índex`

Quan generem la documentació automàticament ens apareixeran a la pàgina Índex totes les paraules que hem determinat que hi surtin sota la lletra de l'abecedari corresponent:

Observi's que a l'exemple hi apareix sota la paraula entrada la paraula índex o sota índex la paraula entrada. Això és així perquè s'ha marcat un concepte amb duess entrades d'índex amb l'ajut d'aquesta sintaxi:
:index:`entrades d'índex <pair: índex; entrada>`

A l'Índex també hi apareixen de manera automàtica tots aquells conceptes que haguem definit sota la directiva de glossari, com ara la paraula entorn:
.. glossary::

   entorn
      Una estructura on... 

Notes al peu

Finalment veurem com crear aquestes petites explicacions sobre un terme que es fan al peu de la mateixa pàgina. No tenen massa sentit en el format de pàgina web, però sí l'adquireixen quan la sortida generada per Sphinx és un document imprimible en format PDF o LaTeX (per passar-lo més endavant a PDF).

El procés és un xic manual tot i que Sphinx s'encarregarà de generar el superíndex i l'enllaç. Primer de tot escrivim aquest codi al punt on volem que aparegui la crida a la nota al peu:
[#notaalpeunúmero]_

i al capdavall del document hi posem el contingut de la nota:

.. [#nota1] Lorem ipsum

El resultat de processar amb Sphinx  és aquest: