Pyramid: documentant amb Sphinx

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

Renderitza en format HTML i EPUB entre d'altres.

Indexa les funcions i objectes i permet la inclusió de comentaris, marques, imatges, etc.

Referències

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/
• Recursos diversos (imatges, todos, etc): https://pythonhosted.org/an_example_pypi_project/sphinx.html

Abans de començar

1. Virtualenv: convé tenir instal·lat sphinx en un virtualenv per no interferir en el sistema (com sempre diem). Per aplicacions de consola i pyramid no sol haver problema: (llegir més avall per apps amb PyQt)

   $ source ~/env/bin/activate

   (env)$ pip install sphinx

2. libs: Caldrà que instal·leu al virtualenv totes les llibreries que el projecte requereix, encara que sigui un buildout i ja les tingui descarregades en local.
3. check: Chequejeu que el vostre projecte funciona (executeu-ho) abans de fer la documentació automàtica. Si no va, el més probable és que la autodoc tampoc.
4. PyQt: Hi ha alguns casos, com els projectes en PyQt, en què es fa molt molest haver de treballar en un virtualenv. El motiu és que la llibreria PyQt s'instal·la com a paquet de sistema, i no hi ha cap package de PYPI que permeti descarregar només els bindings en el virtualenv. En aquests casos, instal·leu sphinx en el sistema, tampoc és un paquet molt intrusiu i no ens ha de donar incompatibilitats.

Tutorial bàsic

Abans de començar comprova que en el virtualenv que utilitzes has instal·lat totes les llibreries que el mòdul a documentar necessita. Si no, sphinx fallrà a l'intentar extreure la informació.

Simplement, prova d'executar-ho dins del virtualenv.

Millor no instal·lar sphinx al sistema, sinó al virtualenv (NO SUDO!).

El tutorial bàsicament es tracta d'utilitzar:

• Activar el nostre virtualenv amb

  $ source env/bin/activate

• Instal·lar sphinx en el virtualenv (NO AL SISTEMA=NO SUDO!) amb:

  (env)$ pip install sphinx

• Crear carpeta de documentació:

  (env)$ mkdir doc

• Entrar-hi:

  (env)$ cd doc

• 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 nostre cas (dins de /doc) seria tan senzill com:

  (env)$ sphinx-apidoc -o . ..

• Incloure el PATH on hi ha el nostre codi a l'arxiu 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()

def 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).

Abans de començar comprova que en el virtualenv que utilitzes has instal·lat totes les llibreries que el mòdul a documentar necessita. Si no, sphinx fallarà a l'intentar extreure la informació.

Simplement, prova d'executar-ho dins del virtualenv.

Millor no instal·lar sphinx al sistema, sinó al virtualenv = NO SUDO! (com sempre).

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.