diumenge, 26 de gener del 2014

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!

dijous, 2 de gener del 2014

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?