Una ullada a Sphinx
Si heu fet servir la documentació de Python, Django o potser alguna de les aplicacions més importants o darrerament li heu fet una ullada al Building Skills with Python us n'adonareu que comparteixen un estil comú. Django ha personalitzat les plantilles, però com podem veure a la part on explica com es crea i es contribueix a la documentació, podem feure que Django fa servir Sphinx.
Sphinx és l'eina amb la qual s'estan creant les documentacions dels principals projectes basats en Python (encara que ens permet escriure qualsevol tipus de documentació) i poc a poc esdevé la killer appplication de la documentació tècnica.
Començar amb Sphinx és prou senzill, sols necessitam tenir Python instal·lat i
$ easy_install Sphinx $ sphinx-quickstart
i anar contestant les preguntes. Si heu compilat alguna vegada algun programa al món Unix veureu com quan acabin les preguntes s''haurà creat un directori amb un arxiu anomenat Makefile (make.bat per altres). Executant-lo ens crearà un directori build amb les bases del que pot ser la nostra documentació.
I és que Sphinx és bàsicament un compilador orientat a la creació de documentació. Agafa documents escrits en Restructured Text i crea un lloc web en HTML, genera un pdf o latex. Això vol dir que per poder treure'n el màxim partit s'ha de conèixer Restructured Text i fer-li una ullada a les comandes que Sphinx incorpora per crear les taules de contingut, fer el resaltat de sintaxi, incorporar imatges o fórmules matemàtiques. Una vegada passat el període d'aprenentatge (que ja us dic que és curt) veureu que el resultats que s'obtenen són espectaculars.
Ja he dit sovint pel blog que m'agrada escriure la documentació (i escriure en general) en text pla, utilitzant LaTeX, Markdown o ResTructured Text. Sphinx ajunta el fet de poder escriure la documentació com m'agrada amb un resultats realment professionals. És a la documentació hipertextual el que LaTeX és per a la documentació científica.
Potser ara us estareu demanant perquè fer la documentació amb aquesta eina i no limitar-nos a un document amb OpenOffice (o fins i tot en Word!!!), se m'acudeixen un parell mallorquí de raons:
- El text pla es pot posar damunt un control de versions.
- Permet que molta gent participi en la creació de la documentació.
- Sphinx ens dóna unes plantilles que fan que la documentació llueixi.
- El ressaltat de sintaxi Python ve de sèrie i costa ben poc fer el ressaltat per altres llenguatges.
- El cercador està inclòs a la documentació
Però sobretot, perquè amb Sphinx escriure documentació és divertit. Pots distribuir-te la feina com vols, no has de passar ànsia per la maquetació final, ni per que les imatges se t'han descol·locat i no saps on han anat a parar (si heu fet documents de més de 20 planes amb un processador de text sabreu què vull dir). I que escriure documentació no sigui feixuc segurament farà que ens faci menys peresa documentar i tothom ens estarà eternament agraït. Jo ja he començat amb la documentació d'appfusedjango que no se digui que no predic amb l'exemple.
Personalment crec que Django ha marcat un abans i un després en el món de la documentació de projectes, de tal manera que cada dia més projectes i aplicacions emulen la manera de documentar de Django i Django (com Python) fa servir Sphinx. Demostrant que per a que un projecte tengui èxit no basta que sigui bo sinó que ha d'estar ben documentat.
No cerquem en Sphinx la bala de plata. Fer bona documentació no és senzill, Sphinx sols fa que sigui menys pesat i ens dóna un resultat final molt més amigable als nostres lectors. Un dels creadors de Django,Jacob Kaplan-Moss, ha escrit un conjunt de posts damunt com s'ha d'escriure bona documentació: Writing great documentation, de lectura imprescindible. Però tot i que no sigui fàcil s'ha de començar, ens hem d'avesar (i jo el primer) a que Sphinx sigui part de les eines de projecte, a escriure documentació i a millorar el nostre estil, tanmateix diuen que la pràctica fa el mestre, no?
