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/

El tutorial bàsicament es tracta d'utilitzar:

• instal·lar (en el virtualenv) amb

  (env)$ easy_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

• 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 . .

• Crear la doc:

  (env)$ make html

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.

Una possibilitat és col·locar-nos en la carpeta just per sobre del nostre python-egg (codi font) just per sota de src.

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

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

   (env)$ cd src/egipcis

3. 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: .
   • Separar doc i arxius de codi: yes
   • autodoc: yes
   • viewcode: crear links al codi dins la doc: yes
4. Crear arxius .rst automàticament. Agafa les fonts de "egipcis" i guarda els .rst en "source":

   (env)$ sphinx-apidoc -o source/ egipcis

5. Editar l'arxiu source/conf.py per arranjar el PATH. A la línia 19 descomentem i afegim:

   ..

6. Crear la doc:

   (env)$ make html

... i ja podem consultar-la amb el navegador a src/egipcis/build/html/index.html