Thanks Martin!

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.