Laboratori 1 i 2 (17-24/02/2011) - Gestió de Documentació Tècnica
Documentació en RestructuredText
L'escriuptura de textos es pot fer amb dos tipus d'eïnes molt diferenciades :
- Programes tipu word, openoffice, etc: intenten que lusuari, alhora que escriu, vegi quelcom que s'assembla a el que s'imprimirà posteriorment.
- Llenguatges mark-up: HTML per exemple, en els quals es col·loquen certs símbols, marques o instruccions entre mig del text desitjat que fan que el tingui un aspecte concret.
Més concretament, hi ha un tipus de llenguatge mark-up anomenat àgil, que és el que s'utilitza en els wiki's. Nosaltres en veurem un, i aprendrem una mica a escriure en aquest llenguatge, que és extraordinadiament senzill. És el reST o restructuredtext.
Pel que fa a la nostra aplicació, malgrat hi hagi altres tipus de llenguetges mark-up al mercat, ens centrarem en reST(reStructuredText), que és el més extès. Aquest llenguatge serà la nostra eïna de documentació de programes, apunts, problemes o projectes que realitzem a partir d'ara.
Algunes de les tècniques bàsiques són:
- Per a títols, subrratllar amb "=" inferior i superiorment.
- Per a títols d'apartat, subratllar inferiorment amb "=".
- Per a subapartats, subratllar amb "-".
- Per ressaltar amb negreta una/es paraula/es, s'envolta la paraula amb dos "*" per banda.
Aquest mateix document és l'aspecte que presenta l'utilització d'aquest mètode, i el procediment que cal seguir per elaborar qualsevol document és el següent:
.. code-block:python_
(virt)d9397992@cceupma4p16:~/rest$ emacs eik.rst
# S'obre un document amb l'emacs o qualsevol editor de textos ( bloc de notas, etc.). Seguidament escribim en forma reST.
(virt)d9397992@cceupma4p16:~/rest$ rst2pdf eik.rst
# S'utilitza aquesta comanda perque ho converteixi a pdf.
(virt)d9397992@cceupma4p16:~/rest$ ls doc.pdf doc.rst doc.rst# doc.rst#~ eik.pdf eik.rst
# S'observa que apareix el document a la carpeta on es guarda.
(virt)d9397992@cceupma4p16:~/rest$ evince eik.pdf
# Per obrir el document final.
L'Sphinx
L'Sphinx és un software que transforma documents escrits en llenguatge reST a presentació HTML, que és el que utilitzen la majoria de pàgines web.
Un cop instal·lat el paquet de l'Sphinx al nostre sistema, notem que apareixen, entre d'altres, dues carpetes significatives:
- Soruces: on s'emmagatzema la documentació escrita en reST.
- Dins aquesta carpeta hi trobem el fitxer Index.rst que és la mare de tots els ous, el document que cita tots els altres documents, els relaciona i automàticament munta a l'HTML uns enllaços per accedir al document anterior, al seguent, etc.
- Build: on es troba documentació ja transformada a html. L'Index.html és la pagina principal, la d'inici.
Treballarem en HTML, no obstant això, cal saber que hi ha infinits formats.
La documentació de python està escrita amb Sphinx. Farem una prova, modificarem un fitxer, anirem a la terminal i desedl directori que te el makefile, executem la comanda make html, i això desenllaça totes les accións necessàries. Reconstrueix la informació. Obrim el document amb el navegador i ho comprovem.
* AUTODOC: eïna dins l'Sphinx que agilitza la documentacio. Entra al fitxer font, extreu la informacio necessaria i l ... si esta escrita en mode reST la sap tibar i ...
Entorn Virtual de Python
Sovint ens trobem que necessitem instal·lar un paquet o programa en un sistema operatiu i no gaudim de privilegis suficients per fer-ho. Una solució a aquest problema és la que es tracta en aquest apartat. Per aprendre això, procedirem a mode d'exemple. Utilitzarem un entorn virtual per a instal·lar paquets de python en un sistema en el qual no en som l'administrador.
- ..(preguntar com es feia)
*** tar zxvf pr1-sphinx.tar.gz (per descomprimir l'arxiu tar, és una instrucció de la consola d'UBUNTU)