diumenge, 13 de desembre de 2015

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:

dimarts, 1 de desembre de 2015

Estructura dels documents amb Sphinx

Quan encetem un projecte de documentació amb Sphinx només seguint les indicacions bàsiques veurem que cada fitxer es converteix en un capítol. Dins d'aquest capítol, amb la formatació RST d'encapçalaments,  podem crear seccions i subseccions. Però, com podem incloure subdocuments dins d'aquesta estructura?. En altres paraules, com dibuixem l'arbre de continguts del document? Com aconseguim una pàgina inicial com aquesta?:


La clau resideix a la directiva toctree (literalment l'arbre de la taula de continguts). Una directiva a RST i a Sphinx és un bloc genèric de marcatge explícit i serveix per indicar quan introduir una imatge, un avís, blocs HTML i altres elements al cos del document. Per exemple, per fer aparèixer una imatge en un punt del document RST escrivim la directiva image:

.. image:: foto.jpg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: text alternatiu
   :align: right

En concret la directiva toctree fa que en aquell punt del document hi aparegui una taula de continguts a base de documents relacionats amb ell. Per exemple, la pàgina índex de l'exemple té una directiva toctree que inclou 3 documents principals o Capítols:

.. toctree::
   :maxdepth: 3
   #:numbered:
   #:caption: Taula de continguts

   introduccio
   cos
   conclusio


on maxdepth defineix la profunditat de la Taula de continguts (fins al nivell 3, encara que usualment és fins a 2).
numbred numerarà els capítols a la Taula
caption és el títol de la Taula, per exemple "Aquí hi trobaràs..."

Si volem que d'un capítol, com ara Cos, pengin diferents documents o subcapítols, només cal que hi tornem a posar una directiva toctree. Per exemple al document que genera el capítol Cos hi ha la directiva:

.. toctree::
   :maxdepth: 2


   cos1
   cos2
   cos3

I al document cos3 s'hi ha inclòs la directiva:

.. toctree::
   :maxdepth: 2


   cos31
   cos32
D'aquesta manera es poden anar niuant uns documents dins dels altres i construir, finalment, l'arbre de continguts.

PS:
1.- El tema d'Sphinx utilitzat a l'exemple, ITCase, es pot descarregar de https://pypi.python.org/pypi/itcase-sphinx-theme/0.2.0

2.- Per catalanitzar-ne els peus i altres detalls només cal entrar al seu directori del nostre ordinador: /home/joan/.local/lib/python2.7/site-packages/itcase_sphinx_theme/itcase

3.-+info: Restructured Text (reST) and Sphinx CheatSheet