Pyramid: documentant amb Sphinx - Historial de revisió

Enric: /* Tutorial bàsic */

2014-05-20T06:55:30Z

Tutorial bàsic

Enric: /* Referències */

2014-05-20T06:54:31Z

Referències

Enric: /* Documentant Pyramid */

2014-05-19T15:35:59Z

Documentant Pyramid

Enric: /* Tutorial bàsic */

2014-05-19T15:34:54Z

Tutorial bàsic

Enric: /* Tutorial bàsic */

2014-05-19T15:34:07Z

Tutorial bàsic

Enric: /* Documentant Pyramid */

2014-05-19T15:32:04Z

Documentant Pyramid

Enric: /* Documentant Pyramid */

2014-05-19T15:31:32Z

Documentant Pyramid

Enric: /* Tutorial bàsic */

2014-05-19T15:30:54Z

Tutorial bàsic

Enric a 21:52, 5 maig 2014

2014-05-05T21:52:12Z

Enric: /* Tutorial bàsic */

2014-05-05T11:13:14Z

Tutorial bàsic

@@ Línia 30: / Línia 30: @@
 Simplement, prova d'executar-ho dins del virtualenv.
-Millor no instal·lar sphinx al sistema, sinó al virtualenv (NO SUDO!).
+Millor no instal·lar sphinx al sistema, sinó al virtualenv (NO SUDO!). Exceptuant projectes amb PyQt (llegir més amunt)
 </div>

@@ Línia 13: / Línia 13: @@
 * 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 ==

@@ Línia 67: / Línia 67: @@
 Simplement, prova d'executar-ho dins del virtualenv.
-Millor no instal·lar sphinx al sistema, sinó al virtualenv.
+Millor no instal·lar sphinx al sistema, sinó al virtualenv = NO SUDO! (com sempre).
 </div>

@@ Línia 24: / Línia 24: @@
 El tutorial bàsicament es tracta d'utilitzar:
 * Activar el nostre ''virtualenv'' amb <pre>$ source env/bin/activate</pre>
-* Instal·lar ''sphinx' en el ''virtualenv'' (NO AL SISTEMA=NO SUDO!) amb:<pre>(env)$ pip install sphinx</pre>
+* Instal·lar ''sphinx'' en el ''virtualenv'' (NO AL SISTEMA=NO SUDO!) amb:<pre>(env)$ pip install sphinx</pre>
-* Crear carpeta de documentació:<pre>$ mkdir doc</pre>
+* Crear carpeta de documentació:<pre>(env)$ mkdir doc</pre>
-* Entrar-hi: <pre>$ cd doc</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'''.

@@ Línia 19: / Línia 19: @@
 Simplement, prova d'executar-ho dins del virtualenv.
-Millor no instal·lar sphinx al sistema, sinó al virtualenv.
+Millor no instal·lar sphinx al sistema, sinó al virtualenv (NO SUDO!).
 </div>
 El tutorial bàsicament es tracta d'utilitzar:
-* instal·lar (en el virtualenv) amb <pre>(env)$ pip install sphinx</pre>
+* Activar el nostre ''virtualenv'' amb <pre>$ source env/bin/activate</pre>
 * Crear carpeta de documentació:<pre>$ mkdir doc</pre>
 * Entrar-hi: <pre>$ cd doc</pre>

@@ Línia 62: / Línia 62: @@
-<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ó.
+<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.
@@ Línia 68: / Línia 68: @@
 Millor no instal·lar sphinx al sistema, sinó al virtualenv.
 </div>
 Farem l'exemple per 1 sol mòdul (egipcis) però podríem tenir diversos dintre de src.

@@ Línia 60: / Línia 60: @@
 * 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.

@@ 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.
 * Pàgina oficial: http://sphinx.pocoo.org/
 * 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 ==
 El tutorial bàsicament es tracta d'utilitzar:
 * 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>
 *: 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 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>
@@ Línia 23: / Línia 32: @@
 <syntaxhighlight lang="python">
 if __name__=="main":
      """MAIN del programa"""
      inicialitza_programa()