Diferència entre revisions de la pàgina «Pyramid: documentant amb Sphinx»
Salta a la navegació
Salta a la cerca
| Línia 16: | Línia 16: | ||
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. | ||
| − | + | 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. | ||
| − | |||
# 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 | + | # 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 (els que no llistem els podeu deixar per defecte):<pre>(env)$ sphinx-quickstart</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 | ||
| + | #* todo: yes | ||
#* viewcode: 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 | + | # Crear arxius .rst automàticament. Agafa les fonts de "egipcis" i guarda els .rst en "source":<pre>(env)$ sphinx-apidoc -o . src/egipcis/egipcis</pre> |
| − | # Editar l'arxiu source/conf.py per arranjar el PATH. A la línia 19 descomentem i afegim: | + | # Editar l'arxiu source/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 | + | ... i ja podem consultar-la amb el navegador a '''doc/_build/html/index.html''' |
Revisió del 11:23, 30 abr 2013
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:
- Pàgina oficial: http://sphinx.pocoo.org/
- Tutorial per un primer projecte: http://codeandchaos.wordpress.com/2012/07/30/sphinx-autodoc-tutorial-for-dummies/
El tutorial bàsicament es tracta d'utilitzar:
- instal·lar (en el virtualenv) amb
(env)$ easy_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
- 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 . .
- Pel cas que estiguem tractant-ho tot des del mateix directori, seria tan senzill com:
- Crear la doc:
(env)$ make html
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.
- Descarregueu el projecte Egipcis de https://github.com/emieza/egipcis.git
- Aneu al directori del buildout on situarem l'arrel de la documentació.
(env)$ mkdir doc
- 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
- Crear arxius .rst automàticament. Agafa les fonts de "egipcis" i guarda els .rst en "source":
(env)$ sphinx-apidoc -o . src/egipcis/egipcis
- Editar l'arxiu source/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')) - Crear la doc:
(env)$ make html
... i ja podem consultar-la amb el navegador a doc/_build/html/index.html
