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!

Qüestionaris a Moodle: Plantilla de resposta en preguntes de Resposta oberta

Les preguntes de resposta oberta són preguntes de qüestionari Moodle que han de ser corregides manualment pel professorat, a diferència de la resta de preguntes que es corregeixen automàticament pel sistema.

L'avantatge d'aquest tipus de pregunta de qüestionari sobre altres formes de lliurar un treball personal al professorat i que aquest el corregeixi passen, sobretot, perquè permeten fragmentar les respostes de manera que sigui molt senzill respondre a cada apartat. Així són útils quan, per exemple, a partir d'un video que l'estudiant veu ha de respondre a tota una sèrie de preguntes que miren d'esbrinar el seu grau de comprensió d'allò que ha vist.

Des de la versió 2.5 de moodle tenim, a més, una nova eina que potencia aquest tipus de pregunta. Es tracta de pautar, de donar pistes i esquemes de resposta a aquestes preguntes que a vegades poden quedar massa generals i no ajuden massa a l'aprenentatge de l'estudiant. Aquesta eina consisteix en crear plantilles per a la resposta de manera que quan  l'estudiant vagi a respondre no es trobi un espai completament net (que a vegades potencia la por al paper en blanc) sinó una bastida sobre la que construir la seva resposta.

Mireu si no és més fàcil respondre aquesta pregunta:

O bé fer un informe sobre un experiment científic:

Com podem fer aquestes plantilles? Res més senzill. Quan estem creant la pregunta de resposta oberta al Banc de preguntes hem de fixar-nos en l'opció Plantilla de resposta a la configuració de la pregunta:

En aquest espai hi podem posar el que vulguem: text, taules, imatges,... i el que hi posem és que després veurà l'estudiant quan vagi a respondre la pregunta. Bona idea, oi?

postach.io

Hi ha moltes eines per crear blogs. Des de les més potents i sofisticades (aquest mateix blogger o wordpress) fins a eines més senzilles que es poden editar des del web o bé en local i, en acabat, penjar al web.

Però avui volem destacar-ne una especialment interessant. Es tracta de postach.io. És una aplicació a la que s'entra identificant-se amb l'identificador d'Evernote i que permet publicar algunes notes del propi Evernote com a entrades d'un blog.

En voleu veure una mostra? Visiteu LaTeX memo http://jqueralt.postach.io/, un lloc on publico notes que prenc sobre solucions que trobo interessants a TeX Stack Exchange http://tex.stackexchange.com/

Com funciona postach.io? Molt senzill: només cal tenir un compte a postach.io  crear-se un blog, configurar-lo (és molt senzill) i aleshores a Evernote creem un notebook nou (jo li dic postach). Quan faig una nota nova, si tinc la intenció de publicar-la, trio abans el notebook postach, faig la nota amb tota la potència de l'editor de l'Evernote i quan acabo l'etiqueto amb l'etiqueta published. Automàticament apareix publicada al blog de postach.io. Genial.

Si fins ara publicar era fàcil, ara, amb eines com aquesta, encara ho és més.

CoursePacker

CoursePacker és una aplicació web http://www.coursepacker.org/ on podem carregar una sèrie de fitxers de text de diferents tipus (html, pdf, odt, txt, doc, docx i rdf), etiquetar-los, dir el tipus de llicència que tenen (usualment variants de les CC), ordenar-los per capítols i seccions i, finalment empaquetar-los (d'aquí el nom)  i previsualitzar-los.

Veurem  que s'ha generat un document únic amb el títol, l'autor i la data, on el programa ha creat una Taula de continguts a partir dels documents aportats amb l'autor, data i llicència de cada article i, a continuació, el contingut del paquet.

Un cop estem segurs que el document resultant és correcte —podem reordenar els articles, afegir-ne o treure'n— el desem i el podem descarregar en format PDF o, millor encara, compartir-ne l'enllaç perquè viu a la web.

El projecte és de CreativeCommons Canada i ha estat llançat recentment aprofitant la Setmana de l'Accés Obert (Open Access Week). L'objectiu, tal com expliquen els autors, és crear paquets de materials educatius —de cursos— i compartir-los fàcilment.

El programa que dóna suport al projecte també és de codi obert i es pot descarregar de github i instal·lar-lo al nostre propi servidor.

Moodlemoot 2013

Ahir es va acabar la Moodlemmot 2013 #mootes13 i com és habitual poso a continuació algunes reflexions i vivències  que hi he tingut.

La primera cosa a destacar és que, per primera vegada, no era una "institució" qui la organitzava (ho solien fer universitats o centres tecnològics públics, tot i que la de l'any passat l'organitzà una universitat privada) sinó directament el moodlepartner català CV&A Consulting. La raó és que ningú s'havia ofert per fer-ho i davant la possibilitat que aquest any no se celebrés van decidir tirar-la endavant amb un temps rècord i recursos limitats.

Però se n'han sortit i molt bé. Se n'han sortit en el temps perquè malgrat tenir tres mesos (un d'ells de vacances) tot ha funcionat com un rellotge. I se n'han sortit en l'organització perquè el llistó de qualitat de les presentacions, tallers i trobades de desenvolupadors ha quedat molt alt. No conec els resultats de les enquestes de satisfacció, però estic segur que els assistents n'hauran donat puntuacions molt altes.
I això haurà estat així gràcies a per una banda l'empenta que en Jordi Vila i el Sr. Calvet des de CV&A han donat al projecte i, per altra, a la feinada que han fet els encarregats de posar-ho a la pràctica, en Javier Sola en primer lloc, seguit per una colla de gent que hi han posat el coll.

El cert és que no han tingut fàcil perquè les aportacions de institucions públiques (gencat, ajuntament, universitats que utilitzen moodle) en aquests temps de vaques flaques ha estat zero. Però se n'han sortit i molt bé. Se'ls ha de felicitar.

I què hi ha hagut en aquesta Moot? Moltes coses i totes interessants.

Ha vingut en Martin Dougiamas a presentar-nos les darreres novetats de moodle. És un home encantador, tranquil, atent, ben educat i amb el cap molt ben moblat. A l'acte de cloenda es va fer una petita performance per celebrar els 10 anys de moodle i va estar encantat, ballant amb la música de moodle  i signant  cartells:

Les novetats que presentà per la versió 2.6 i posteriors no són tan espectaculars per l'usuari final com les que hi ha hagut en versions anteriors, però déu-n'hi do. Se centren en millorar la interfície i les notificacions per adaptar-les plenament a dispositius mòbils, millores en l'anàlisi de dades i estadístiques i petits avançaments als fòrums i anotació de PDF (que faran gaudir a alguns que conec).

Sembla, però, que a can moodle estan retornant als orígens i deixant la tecnologia en segon terme per posar com a prioritari la pedagogia. Perquè no ho oblidem: moodle serveix per facilitar l'ensenyament i l'aprenentatge.

En Martin va parlar també de la Moodle Research Conference que tindrà lloc la setmana que ve a Tunísia i de les preguntes sobre les que tractaran i, finalment, parlà de la joia de la corona d'aquest setembre: el MOOC learnmoodle, el primer que s'ha fet amb i sobre moodle i que ha estat un èxit mundial. Sembla ser que volen oferir còpies de seguretat per qui el vulgui replicar al seu lloc o per traduir-lo.

Una de les novetats de la versió 2.5 són les insígnies i això s'ha traduït en què s'han convertit en una de les estrelles de la moot. Hi van haver diferents tallers d'en Javier Sola sobre insígnies adreçats tant a professorat com a administradors i un parell de xerrades d'en Gavin Henrick una sobre l'ús de les insígnies i l'altra sobre gamificació. La introducció de les insígnies ha estat molt ràpida i des que la Mozilla Foundation en començà a parlar ara deu fer cosa d'un any i mig ha tingut un èxit sorprenent. Hem de començar a plantejar-nos donar-les un és intensiu.

Un altre punt d'interès d'aquesta moot han estat les sessions per donar a conèixer l'activitat Taller, que permet tant l'autoavaluació com l'avaluació entre iguals. En David Pinyol va impartir tres tallers pràctics sobre aquesta activitat amb força èxit de públic. També vàrem presentar conjuntament un taller anomenat Big Mac Moodle, moodle amb extra de tot on presentàvem les diferents possibilitats de treball en grup que es pot fer amb moodle.

Amb en Sebastián Torres vàrem fer una sessió sobre Mahara, una petita maharamoot. Vàrem exposar les nostres experiències sobre l'ús del portafolis amb persones adultes i la integració Moodle i Mahara, en acabat els participants varen entrar a Mahara i el varen descobrir: tothom en va sortir encantat. Tot i això s'ha de reconèixer que costa molt introduir el concepte de portafolis en aquest país.

Les moot serveixen també per retrobar amics i fer coneixences i aquest no n'ha estat l'excepció. Algú deia que sempre som els mateixos, però no ho crec. És cert que hi ha un nucli d'incondicionals que fallem molt poc, però sempre hi ha gent nova que s'hi afegeix i les gaudeix.

Em deixo moltes coses per dir i molts noms per citar, però com que diuen que una imatge val més que mil paraules us remeto a les fotos de la moot per descobrir-hi i veure els companys: http://m.flickr.com/#/photos/mootes13/

Notes sobre Irlanda

Aquest estiu, i de forma impensada, hem anat a petar a Irlanda, un petit país europeu en una illa atlàntica no tan petita. Vet aquí algunes idees soltes i sense cap ordre sobre el país que no m'agradaria oblidar:

• Hi ha una bona xarxa d'autovies amb pocs peatges, i els pocs molt barats. Vam anar de Cork a Dublín per 3€ (Barcelona-València: 35€). Les carreteres secundàries són prou bones i es presta molta atenció als vianants quan es travessa una població, amb dissuassors de velocitat a l'entrada si cal. Les carreteres de poble són totes asfaltades, però molt estretes i sense voral per on els locals circulen a velocitats de vertigen, fet que — afegit a la conducció per l'esquerra— fa certament perillosa la circulació als europeus continentals. 
• El combustible una xic més car que aquí però amb competència real: només avançant un parell de Km es pot trobar més car o més barat (fins a 20 cèntims per litre de diferència).
• El clima és atlàntic, vol dir que cada dia sol caure una mica de pluja, bastant pluja o molta pluja. Rarament es veu un dia de sol amb el cel blau, a tot estirar alguna estona. La resta de temps el cel està ennuvolat i —si fa "bon dia"— no plou massa. Els irlandesos, però, no estan gens preocupats i van ben preparats per les inclemències. Quin remei!
• L'abundància de pluja permet que la vegetació creixi per tot arreu amb prats i boscos permanentment verds. A més, als irlandesos els agraden força les flors (suposo per donar un toc de color a l'ambient tristoi del cel ennuvolat) i tenen flors i jardins ben cuidats per tot arreu.
• La natura de l'illa no està gens malmesa per contaminació industrial i hi ha una gran abundància d'ocells tant marins com terrestres que fan les delícies dels birdwatchers. A més d'ocells també vàrem tenir la sort d'observar una guineu, cérvols, una llebre, foques  i una gernació de vaques i ovelles de tots colors i races.
  
• El te i el cafè són servits en grans recipients que els fan completament aigualits. Però a totes les habitacions d'hotels i B&B hi ha un bullidor d'aigua i sobrets de te o cafè per preparar-se un mateix. Aquí sí que surt bo amb les proporcions adients d'aigua!
• La cervesa és l'altra beguda nacional i se serveix en gots d'1 pinta (=568 ml, una mica més de mig litre) o de mitja. La rossa es pren tal qual surt del barril, però la negra (Guiness principalment) s'ha de deixar reposar perquè l'escuma pugi a dalt de tot. Boníssimes totes. Els pubs o cafeteries estan a partir de l'abertura (mig matí) sempre poblats per bebedors de cervesa.
• El menjar és força bo tot i que una mica més car que aquí (com tot: tenen un IVA del 23%) i es pot menjar bé en bars i restaurants a pràcticament qualsevol hora. Els àpats consisteixen en un bon esmorzar (de forquilla), un dinar més lleuger i un sopar no massa d'hora tampoc. Als restaurants tenen menús més barats pels earlybirds que sopen entre les 6 i les 8. La carn és tendríssima i de peix hi ha el típic fish and chips o el salmó que no es pot deixar perdre. Tenen mil i una manera de fer les patates, però totes són igualment bones perquè la matèria prima és de primera.
• La gent és amable i s'esforcen en parlar anglès, però a mi em costava d'entendre'ls, probablement per l'accent particular. Per exemple el 8 el diuen semblant a [eis] més que no pas a [eit]. També va a zones: Dublín els entenia millor que no pas a l'oest del país on, suposo, hi ha més parlants del gaèlic.
• El gaèlic es parla, però no massa. A les illes d'Aran és l'idioma principal i hi ha escoles on els joves que el volen aprendre hi van a parlar-lo. També hi ha alguna emissora de ràdio en gaèlic i tots els noms de poblacions i cartells de trànsit estan en els dos idiomes, però em sembla que la salut d'aquest idioma tan a prop de l'anglès no és massa bona.
• A diferència de Croàcia, on vam estar l'any passat, aquí no es veu un sentiment nacionalista tan fort. Alguna bandera d'Irlanda en algun poble en festes, les banderes oficials i poca cosa més. Suposo que el fet de ser independents des de fa més temps refreda els ànims i consolida i normalitza el concepte de país.

Resumint: un lloc per tornar-hi.

10 anys —Part II: Moodle—

En aquesta segona entrada de la sèrie del desè aniversari parlaré de Moodle. L'agost de l'any 2002 en Martin Dougiamas va presentar a la comunitat el primer moodle però jo no en vaig sentir a parlar fins l'any següent, arran d'una notícia que va publicar Octeto, la revista electrònica del CENT de la Universitat Jaume I.

En aquell primer trimestre del 2003 jo anava darrera d'un LMS de codi lliure anomenat Bazaar basat, si no recordo malament, en Perl i que feia córrer el campus virtual de la universitat canadenca d'Athabasca. Era molt potent i feia moltes coses: fòrums, xats, correu intern, presentació de recursos, seguiment dels estudiants ... Fins i tot, amb el desig de tenir un campus propi, vaig entrar en contacte amb gent de la UPC per veure quines possibilitats hi havia d'instal·lar-lo i fer-lo córrer. Malauradament el preu excedia el pressupost previst i ho vaig haver de deixar córrer.

Afortunadament aleshores va ser quan vaig conèixer moodle. La primera notícia la vaig llegir també a Octeto i quan vaig veure a moodle.org la documentació sobre instal·lació, com que tenia una certa experiència amb altres programes basats en PHP i MySQL, vaig descarregar-me'l i instal·lar-lo en local, al meu ordinador, que aleshores corria amb uindous i on hi tenia un servidor Wamp (em sembla que usava EasyPHP). Al maig de 2003 vaig fer una instal·lació de moodle en local amb èxit complet, era la versió 1.0.9.

Una instal·lació en local de moodle, com de qualsevol altre programa social, té poca emoció. Com que la màgia es veu quan s'utilitzen els diferents rols (admin, professor, estudiant) calia entrar i sortir contínuament del programa i es feia difícil apreciar les possibilitats. Per això al juny vaig intentar d'instal·lar moodle a webcindario, un lloc gratuït amb suport de php/mysql, però sense massa èxit. Hi havia problemes en la càrrega de fitxers per FTP i, un cop solucionats, d'arrencada, en local és on anava millor.

Com que hi havia bastanta feina a traduir vaig donar un cop de mà als companys de la UJI que des del principi han liderat la traducció catalana de la interfície de moodle. Després hi he tornat de tant en tant, traduint algun mòdul no estàndard i,coincidint amb l'arribada de la versió 2 de moodle, vam organitzar amb en Carles Bellver (@carlesbellver) la Marató de traducció durant els nadals de 2011. Moodle va molt de pressa en el seu desenvolupament, i sempre cal córrer una mica per no perdre el tren de les traduccions.

Per acabar amb la Prehistòria: al setembre de 2003 vam llogar un espai en un servidor comercial seriós (http://www.arsys.es/) i hi vàrem fer una instal·lació de la versió 1.1.1 per posar en producció el primer curs de Moodle dels estudis de GES a distància. Aquest primer curs el vàrem fer amb la Mariona Linares (@marionalinares) i es deia Llengua i TIC.

Aquell curs —on es treballaven els blogs, els fòrums, i altres novetats d'internet— va ser la primera pedra sobre la que s'ha bastit un campus virtual que ens ha dut, ara mateix, a tenir 5000 estudiants adults de GES estudiant completament a distància i, el que és millor, sortint se'n amb èxit. Què hagués passat si no hagués existit Moodle?