Diferència entre revisions de la pàgina «Pyramid: documentant amb Sphinx»

De Cacauet Wiki
Salta a la navegació Salta a la cerca
Línia 9: Línia 9:
 
== Tutorial bàsic ==
 
== Tutorial bàsic ==
 
El tutorial bàsicament es tracta d'utilitzar:
 
El tutorial bàsicament es tracta d'utilitzar:
* instal·lar (en el virtualenv) amb <pre>(env)$ easy_install sphinx</pre>
+
* instal·lar (en el virtualenv) amb <pre>(env)$ pip install sphinx</pre>
 
* 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'''):<pre>(env)$ sphinx-quickstart</pre>
 
* 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'''):<pre>(env)$ sphinx-quickstart</pre>
 
*: IMPORTANT: Activeu les funcions '''autodoc, todo i viewcode'''.
 
*: IMPORTANT: Activeu les funcions '''autodoc, todo i viewcode'''.

Revisió del 11:13, 5 maig 2014

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:


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.