Pyramid: documentant amb Sphinx

Sphinx és un software per documentació de projectes en Python.

Realitzar un primer projecte pot no ser massa complicat si no tenim una estructura de directoris massa complexa. El següent tutorial us pot ajudar:

• Pàgina oficial: http://sphinx.pocoo.org/
• Tutorial per un primer projecte: http://codeandchaos.wordpress.com/2012/07/30/sphinx-autodoc-tutorial-for-dummies/

Tutorial bàsic

El tutorial bàsicament es tracta d'utilitzar:

• instal·lar (en el virtualenv) amb

  (env)$ pip install sphinx

• sphinx-quickstart: una utilitat interactiva que a través d'unes preguntes ens crearà una configuració bàsica per crear el projecte (arxiu conf.py):

  (env)$ sphinx-quickstart

  IMPORTANT: Activeu les funcions autodoc, todo i viewcode.

• sphinx-apidoc: ens generarà automàticament els arxius .rst necessaris per generar cada mòdul (arxiu .py).

  (env)$ sphinx-apidoc -o <dir_sortida> <dir_fonts>

  Pel cas que estiguem tractant-ho tot des del mateix directori, seria tan senzill com:

  (env)$ sphinx-apidoc -o . .

• Si ho estem fent al mateix directori potser no cal, però si hem triat una altra carpeta per col·locar la doc, caldria posar-la en el PATH del conf.py (a la línia 19 ja surt comentat, potser només cal descomentar-lo i/o afegir-hi el path que ens convingui):

  sys.path.insert(0, os.path.abspath('.'))

• Crear la doc:

  (env)$ make html

Ull amb els mains

És possible que no es generi bé la doc si algun dels vostres mòduls (arxius .py) té el codi escrit directament sense encapsular en cap funció o "main". Ens cal encapsular el codi (wrap) en el típic "main" de Python:

if __name__=="main":
    """MAIN del programa"""
    inicialitza_programa()
    dades = carrega_dades()
    ...

Podeu adonar-vos d'aquest error perquè no genera cap HTML o bé perquè executa el nostre programa, cosa que no ha de fer.

Documentant Pyramid

Però si anem a documentar un projecte com un Pyramid, en què tenim els arxius en diverses carpetes i volem guardar un cert ordre, convé fer algunes modificacions del procediment del tutorial.

Podeu agafar el projecte exemple dels Egipcis per practicar i després fer-ho en el vostre.

La situació és aquesta:

• Tenim un sol mòdul, el codi font del qual està a src/egipcis
• La doc la volem a l'arrel del projecte (buildout).

Farem l'exemple per 1 sol mòdul (egipcis) però podríem tenir diversos dintre de src.

1. Descarregueu el projecte Egipcis de https://github.com/emieza/egipcis.git
2. Aneu al directori del buildout on situarem l'arrel de la documentació.

   (env)$ mkdir doc

3. I entrem:

   (env)$ cd doc

4. Inicialitzem sphinx i responem amb els següents paràmetres (els que no llistem els podeu deixar per defecte):

   (env)$ sphinx-quickstart

   • Directori per la doc: .
   • autodoc: yes
   • todo: yes
   • viewcode: crear links al codi dins la doc: yes
5. Crear arxius .rst automàticament. Agafa les fonts de "egipcis" i guarda els .rst al directori "doc" (.):

   (env)$ sphinx-apidoc -o . ../src/egipcis/egipcis

6. Editar l'arxiu doc/conf.py per arranjar el PATH. A la línia 19 descomentem l'addició del "." al path i afegim:

   sys.path.insert(0, os.path.abspath('../src/egipcis'))

7. Crear la doc:

   (env)$ make html

... i ja podem consultar-la amb el navegador a doc/_build/html/index.html

Si tenim diversos mòduls

Ull, si tenim diversos mòduls al generar els .rst amb apidoc pot ser que se'ns "matxaqui" l'arxiu modules.rst

Això es pot solventar fent el output del apidoc en una altra carpeta i despres "fusionar" els "modules.rst". Al final, modules.rst ha de tenir una pinta com aquesta:

egipcis
=======

.. toctree::
   :maxdepth: 4

   egipcis
   modul2
   modul3
   etc

Cadascun d'aqeusts noms indicats al modules.rst ha de ser al seu torn un mòdul a la carpeta "src" i hem de generar amb apidoc el seu .rst que el podem situar a l'arrel del directori "doc".

També es pot generar l'apidoc de tots els mòduls amb:

(env)$ sphinx-apidoc -o . ../src/*

...pot ser, però, que ens agafi alguns arxius "sueltus" .py que no volem com el setup.py, etc.