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

De Cacauet Wiki
Salta a la navegació Salta a la cerca
(Es crea la pàgina amb «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 c…».)
 
 
(Hi ha 21 revisions intermèdies del mateix usuari que no es mostren)
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
 +
 +
 +
== Abans de començar ==
 +
# '''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)
 +
#:<pre>$ source ~/env/bin/activate</pre>
 +
#:<pre>(env)$ pip install sphinx</pre>
 +
# '''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.
 +
# '''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.
 +
# '''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.
 +
 +
<br>
 +
 +
== Tutorial bàsic ==
 +
<div class="exercici">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)
 +
</div>
  
 
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>
+
* Activar el nostre ''virtualenv'' amb <pre>$ source env/bin/activate</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>
+
* Instal·lar ''sphinx'' en el ''virtualenv'' (NO AL SISTEMA=NO SUDO!) amb:<pre>(env)$ pip install sphinx</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>
+
* Crear carpeta de documentació:<pre>(env)$ mkdir doc</pre>
*: Pel cas que estiguem tractant-ho tot des del mateix directori, seria tan senzill com:<pre>(env)$ sphinx-apidoc -o . .</pre>
+
* Entrar-hi: <pre>(env)$ 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>
 +
*: 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>
 +
*: Pel nostre cas (dins de /doc) seria tan senzill com:<pre>(env)$ sphinx-apidoc -o . ..</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>
 +
 +
<br>
 +
=== 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:
 +
 +
<syntaxhighlight lang="python">
 +
if __name__=="main":
 +
    main()
 +
 +
def main():
 +
    """MAIN del programa"""
 +
    inicialitza_programa()
 +
    dades = carrega_dades()
 +
    ...
 +
</syntaxhighlight>
 +
 +
Podeu adonar-vos d'aquest error perquè no genera cap HTML o bé perquè executa el nostre programa, cosa que no ha de fer.
 +
 +
<br>
  
 
== Documentant Pyramid ==
 
== 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.
 
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 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).
 +
 
 +
 
 +
<div class="exercici">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).
 +
</div>
 +
 
 +
 
 +
Farem l'exemple per 1 sol mòdul (egipcis) però podríem tenir diversos dintre de src.
  
Podeu agafar el projecte dels Egipcis per practicar i després fer-ho en el vostre.
 
 
# Descarregueu el projecte Egipcis de https://github.com/emieza/egipcis.git
 
# Descarregueu el projecte Egipcis de https://github.com/emieza/egipcis.git
# Aneu al directori src/egipcis on situarem l'arrel de la documentació.<pre>(env)$ cd src/egipcis</pre>
+
# Aneu al directori del buildout on situarem l'arrel de la documentació.<pre>(env)$ mkdir doc</pre>
# Inicialitzem sphinx i responem amb els següents paràmetres:<pre>(env)$ sphinx-quickstart</pre>
+
# I entrem:<pre>(env)$ cd doc</pre>
 +
# Inicialitzem sphinx i responem amb els següents paràmetres (els que no llistem els podeu deixar per defecte):<pre>(env)$ sphinx-quickstart</pre>
 
#* Directori per la doc: .
 
#* Directori per la doc: .
 
#* autodoc: yes
 
#* autodoc: yes
#* Separar doc i arxius de codi: yes
+
#* todo: yes
#* Crear links al codi dins la doc: yes
+
#* viewcode: crear links al codi dins la doc: yes
# Crear arxius .rst automàticament. Agafa les fonts de "egipcis" i guarda els .rst en "source":<pre>(env)$ sphinx-apidoc -o source/ egipcis</pre>
+
# Crear arxius .rst automàticament. Agafa les fonts de "egipcis" i guarda els .rst al directori "doc" (.):<pre>(env)$ sphinx-apidoc -o . ../src/egipcis/egipcis</pre>
 +
# Editar l'arxiu doc/conf.py per arranjar el PATH. A la línia 19 descomentem l'addició del "." al path i afegim:<pre>sys.path.insert(0, os.path.abspath('../src/egipcis'))</pre>
 
# Crear la doc:<pre>(env)$ make html</pre>
 
# Crear la doc:<pre>(env)$ make html</pre>
... i ja podem consultar-la amb el navegador a src/egipcis/build/html/index.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.

Revisió de 06:55, 20 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[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.