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 1: Línia 1:
Sphinx és un software per documentació de projectes en Python.
+
Sphinx és un software per documentació automàtica 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:
+
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/
 
* 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 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
  
 
== 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)$ pip install sphinx</pre>
 
* instal·lar (en el virtualenv) amb <pre>(env)$ pip install sphinx</pre>
 +
* Crear carpeta de documentació:<pre>$ mkdir doc</pre>
 +
* Entrar-hi: <pre>$ cd doc</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'''.
 
* sphinx-apidoc: ens generarà automàticament els arxius .rst necessaris per generar cada mòdul (arxiu .py). <pre>(env)$ sphinx-apidoc -o <dir_sortida> <dir_fonts></pre>
 
* sphinx-apidoc: ens generarà automàticament els arxius .rst necessaris per generar cada mòdul (arxiu .py). <pre>(env)$ sphinx-apidoc -o <dir_sortida> <dir_fonts></pre>
*: Pel cas que estiguem tractant-ho tot des del mateix directori, seria tan senzill com:<pre>(env)$ sphinx-apidoc -o . .</pre>
+
*: Pel nostre cas (dins de /doc) seria tan senzill com:<pre>(env)$ sphinx-apidoc -o . ..</pre>
* 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):<pre>sys.path.insert(0, os.path.abspath('.'))</pre>
+
* 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):<pre>sys.path.insert(0, os.path.abspath('..'))</pre>
 
* Crear la doc:<pre>(env)$ make html</pre>
 
* Crear la doc:<pre>(env)$ make html</pre>
  
Línia 23: Línia 32:
 
<syntaxhighlight lang="python">
 
<syntaxhighlight lang="python">
 
if __name__=="main":
 
if __name__=="main":
 +
    main()
 +
 +
def main():
 
     """MAIN del programa"""
 
     """MAIN del programa"""
 
     inicialitza_programa()
 
     inicialitza_programa()

Revisió del 21:52, 5 maig 2014

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:

Tutorial bàsic

El tutorial bàsicament es tracta d'utilitzar:

  • instal·lar (en el virtualenv) amb
    (env)$ pip install sphinx
  • Crear carpeta de documentació:
    $ mkdir doc
  • Entrar-hi:
    $ 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).

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.