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:

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

Els èxits dels passats sistemes educatius

Per la meva avançada edat em va tocar cursar el Batxillerat del Pla del 64 . Es distingia de l'anterior -que va cursar mon germà i del qual no vaig poder aprofitar massa llibres, vés per on- en la introducció d'allò que en deien la "Matemàtica moderna" que consistia en explicar a nens de 10 anys la teoria de conjunts. Teoria que vaig entendre i fruir quan cursava COU amb 18, però no abans. Recordo que els títols en castellà dels llibres de mates eren  Grupo o Cuerpo i després he entès que feien referència a l'estructura dels conjunts respecte a les operacions que s'hi poden definir.

Que t'expliquessin les fraccions no com a trossets de pastís, que és el més habitual, sinó com a classes d'equivalència no ajudava massa a entendre-les, però què hi havíem de fer. Vivíem en la darrera dècada del franquisme i poc s'hi podia dir. Rectifico: vivíem en la dècada anterior a la mort del dictador, que el franquisme encara dura.

Aquell Batxillerat es caracteritzava, entre moltes altres desgràcies curriculars, per l'existència de dos exàmens anomenats de Revàlida que es feien un cop superats el 4t i el 6è curs. Així, jo tinc el 6è de Batxillerat i revàlida. Gran cosa.

Ara no faré una llista exhaustiva de les diferents lleis d'educació que han vingut després, però les que més han durat o han donat més tema de conversa han estat la Llei General d'Educació, que va introduir l'EGB i el BUP, i la LOGSE que va elevar als 16 anys l'escolaritat obligatòria amb l'ESO. La darrera, però, és la LOMQE, la llei Wert vaja, que com a màxima novetat retorna als exàmens de revàlida, a la memorització, a la religió catòlica avaluable (perquè no l'hinduisme?) i a la segregació per aptituds.

És a dir, tornem al passat. I amb quins criteris ens poden vendre aquest retorn? A veure, si els actuals dirigents del país tenen la meva edat o són un pèl més vells vol dir que van passar pel vell Batxillerat del què parlava a l'inici, el de les revàlides. Doncs si aquests senyors només poden exhibir com a èxit propi haver enfonsat caixes d'estalvi, empobrit un país, cobrir-se de corrupció i augmentar les ganes de marxar-ne, com podem dir que els seus estudis sí que formaven i els posteriors no? Que els que ells van cursar eren bons i els que van venir després espatllaven les criatures? Com poden dir-nos que amb el retorn de les revàlides els estudiants estaran més formats. Per fer què? El mateix que ells?

No vull establir una correlació directa entre exàmens de revàlida i ineptitud política, però potser algun matemàtic serà capaç de fer-ho.

La formació d'adults a distància i els centres presencials: 1 - moodle

Aquest divendres passat vaig tenir l'honor, juntament amb el company @tinoserra, de presentar la formació a distància que fem a Catalunya als companys de les escoles d'adults d'Alacant, en una jornada organitzada pel Cefire d'Alacant al CFPA Joan Lluís Vives d'Ibi.

A les trobades de mestres, encara que hi vagi a presentar el que fem,  sempre s'aprèn (i molt) dels companys. Difícilment aplicarem fil per randa el que es fa en un altre lloc, això no m'ha passat mai ni quan estava en una escola presencial i sentia el que feia una altra. El que sí que em passa és que se'm mobilitzen les neurones i el pensament em va a cent.

Aquest dia vaig sentir les experiències dels companys en centres presencials del País Valencià que no fan coses massa allunyades de les que fan les escoles d'adults a casa nostra. Formació de base (alfa, neo i certif, que en dèiem), GES, proves d'accés, valencià i el programes J, que són els ensenyaments no-reglats que molts cops s'ofereixen amb la col·laboració d'altres entitats locals o a través de l'Associació d'alumnes.

Els problemes d'aquells centres són els mateixos que els d'aquí i són els de sempre, amb el temps la formació d'adults no ha millorat massa. El que per a mi sempre ha caracteritzat aquesta branca de l'educació, però, és l'empenta del professorat que hi treballa. Malgrat les dificultats el professorat d'adults sempre hem estat capdavanters en quasi bé tot. En la introducció de portafolis, en els treballs col·laboratius i per projectes, en l'ús intensiu de les tecnologies,... I això segueix.

Moodle és la meva segona casa, és el segon lloc on passo més hores al dia. Ja sé que hi ha qui l'ha enterrat cent vegades i escoltant els companys en algun cas jo també ho hagués fet i, fixeu-vos en el que diré ara, potser ho hagi d'acabar fent d'aquí a no massa, i no per ganes, sinó per reacció.

Fins no fa gaire l'administració educativa valenciana oferia als centres allotjament gratuït per a moodle i altres programes basats en php-mysql, com ara joomla . Però a causa dels forats de seguretat aquest espai es tanca. Ja sé que la millor manera de protegir un ordinador és tenint-lo tancat (xist) però hi ha maneres molt vàlides de seguir oferint servei sense negar-lo, tot i que sembla que no és el cas. Com alternativa s'ofereix als centres la utilització d'una "plataforma" anomenada mestre@casa. Visiteu la secció Webs de centre, penseu en moodle i reprimiu una llagrimeta.

Desapareixeran les aules virtuals. Milers i milers d'euros i d'hores de formació i d'aprenentatge amb moodle llençats per no oferir una alternativa vàlida com ho és, per exemple, àgora.

Però queda un petit reducte gal (no es pot anar contra corrent ni contra els temps). Les associacions d'alumnes no formen part de l'administració, són entitats independents que presten un gran suport als centres d'adults i, quan un d'ells pensa que al 2014 ja no es pot passar sense una aula virtual, li donen un cop de mà i cerquen un servidor comercial amb un bon suport.

Entenc els desesperats de moodle, entenc que blasmin moodle quan esperen que els doni servei i veuen que les pàgines no baixen, que triguen moltíssim, que se'ls talla la connexió a mitja feina... M'ha passat i sé com se sent un. Però cal identificar les causes i posar-hi remei. Moodle és ràpid si les connexions són ràpides i l'allotjament és bo. He treballat amb moodles allotjats a l'altra punta de món amb una rapidesa increïble. Per tant, no és moodle: és on viu i com ens arriba.

Per això, si es creu en moodle, en el que fa, i es vol fer servir en condicions,  cal prendre decisions i buscar solucions. N'hi ha, creieu-me.

Instal·lació de temes a Sphynx

Tot i que sphynx porta uns quants temes per defecte, tenim la possibilitat d'utilitzar-ne de nous bé creats per alguna institució bé per algun programador individual.

Podem trobar-los fent una cerca a l'índex de paquets de Python: PyPI - the Python Package Index. Això ens donarà una llarga llista no solament de temes sinó de connectors que es poden afegir a  sphynx.

Un de força interessant és el tema que utilitzen els documents allotjats al lloc Read the docs (basats en sphinx) ique es troba en el paquet sphinx_rtd_theme. És molt fàcil d'instal·lar si es té prèviament instal·lada l'eina d'instal·lació de paquets de Python pip, només cal escriure en un terminal l'ordre:

pip install sphinx_rtd_theme

Un cop instal·lat a l'equip per poder-lo fer servir amb els nostres documents només cal que afegim al nostre fitxer conf.py les següents línies:

    import sphinx_rtd_theme

    html_theme = "sphinx_rtd_theme"

    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Compte Xtec a gmail

Si centralitzeu tot el vostre correu en un sola bústia de gmail i hi llegiu també el correu d'Xtec a partir d'ara, i cada 6 mesos, us veureu obligats a canviar la contrasenya.

Com que d'una vegada per l'altra ens oblidarem de com vàrem fer-ho el darrer cop vet aquí un petit recordatori per no perdre-hi massa temps.

1.- Entrem al nostre compte de gmail i fem clic a la rodeta de configuració (1) i del menú triem un altre cop Configuració.

2.- Se'ns obrirà aquesta pàgina en la qual cliquem a la pestanya Comptes (2) i veurem els que llegim en aquesta bústia, en el cas de la captura el de gmail i el d'xtec. Ens interessen els altres comptes (3) i farem clic a edita la informació.

3.- Això fa que s'obri una finestreta:

4.- Escrivim la nova contrasenya (1) que ha de tenir entre 8 i 30 caràcters. Ha d'estar formada per una combinació de lletres minúscules, lletres majúscules, números i signes com ! @ # $ % _ & = - + *  Com a mínim ha d'haver-hi 2 números, 2 lletres minúscules i 1 lletra majúscula.

5.- Finalment cliquem el botó Desa els canvis i tornem a la safata d'entrada de gmail.

Sphinx, una eina per crear documentació

Què tenen en comú el Manual de l'usuari de Mahara i la Documentació no oficial de Sublime Text, l'excel·lent editor de codi i text? Si visiteu ambdós llocs us trobareu amb un espai web molt ben estructurat i organitzat, amb informació rica i fàcil de trobar gràcies al formatatge del contingut. És a dir, són llocs que tots voldríem tenir per a mostrar la nostra documentació.

Doncs ho podem tenir perquè el programa que construeix aquests llocs és Sphinx, una eina de codi lliure que corre sobre Python. Sphinx treballa amb fitxers de text pla escrits en el format reStructuredText, una variant del llenguatge de marques markdown sobre el qual ja hem parlat en alguns articles d'aquest blog. Sphinx processa la informació d'aquests fitxers rst i el resultat entre d'altres característiques és:

• Una gran varietat de formats de sortida: HTML, LaTeX, PDF, epub, text pla,...
• Ús extensiu de referències creuades amb enllaços automàtics.
• Estructura jeràrquica de la informació amb la creació d'un arbre del seccionat del document.
• Generació automàtica d'índexs

Per obtenir un resultat ben organitzat cal que tinguem la documentació original també ben organitzada. 

D'entrada necessitem un document inicial, anomenat index.rst o inici.rst, on consti quins fitxers s'inclouran en l'arbre de la documentació i en quin ordre. També hi podem dir com volem les seccions del document i si necessitem una pàgina amb un índex i una altra de cerca. Típicament aquest fitxer té aquest contingut:

Títol de la documentació  

========================

.. toctree::

   :numbered:

   :maxdepth: 2

   introduccio

   cos

   conclusio

:ref:`genindex`

:ref:`search`

Veiem que les seccions i subseccions seran numerades i que la profunditat de l'índex és de 2, és a dir, a l'índex apareixeran seccions i subseccions (tot i que al document hi poden haver unitats d'ordre inferior). La documentació —que té com a títol Títol de la documentació— inclourà tot allò que hi hagi en 3 fitxers de tipus rst: introduccio.rst, cos.rst i conclusio.rst. A més, quan es generi la sortida en HTML s'inclourà una pàgina d'índex (amb les entrades que hi haguem marcat) i una altra molt potent de cerca.

La instal·lació de Sphinx és molt senzilla si al nostre Ubuntu ja hi tenim instal·lat el Python, només cal obrir una finestra de terminal i escriure: easy_install -U Sphinx

Això instal·larà la darrera versió d' Sphinx al nostre ordinador. Aleshores podem crear un directori de treball on crear la documentació, entrar-hi i deixar que  Sphinx creï el sistema de fitxers i subdirectoris.

Tot això es fa amb l'ajut de l'script

sphinx-quickstart

que executem en la mateixa terminal. Simplement responent les senzilles preguntes que ens va plantejant l'script finalment crea tota l'estructura necessària per crear els diferents formats de sortida de la documentació. Aquesta informació queda emmagatzemada en un fitxer anomenat conf.py que sempre podrem editar i canviar al nostre gust, però si més no ens ajuda a començar.

El següent pas és editar el fitxer inici.rst i crear els fitxers també de tipus rst on inclourem la documentació. Per editar el llenguatge rst ho podem fer amb qualsevol editor de text, especialment amb algun que tingui una extensió que ens acoloreixi la sintaxi, però si no ens hi volem trencar el cap hi ha editors en línia, com ara l'Online reStructuredText editor que ens facilita l'escriptura de la sintaxi alhora que ens permet visualitzar el resultat en format HTML, molt útil.

Bé, ja ho tenim tot, tenim Sphinx instal·lat i funcionant, tenim la configuració preparada al nostre gust, tenim la informació de la documentació organitzada en diferents fitxers font, només queda fer que Sphinx ens produeixi la sortida desitjada, com ho fem?

Obrim una terminal en el directori on hi ha la documentació i escrivim alguna d'aquestes ordres:

• make html per obtenir la sortida en format HTML
• make latex per tenir un fitxer font tex que podem editar al nostre gust i passar-lo quan vulguem a PDF.
• make pdflatex per obtenir directament un fitxer PDF però que prèviament haurà passat per LaTeX. També editable.
• make epub  per obtenir la sortida en format epub. Mol t potent i útil.

Per acabar: una eina potentíssima per obtenir documentació de gran qualitat. Vinga, a escriure!