Pyramid: documentant amb Sphinx

De Cacauet Wiki
Salta a la navegació Salta a la cerca

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[modifica]

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:


Abans de començar[modifica]

  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[modifica]

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!). Exceptuant projectes amb PyQt (llegir més amunt)

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[modifica]

É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[modifica]

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[modifica]

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.