Diferència entre revisions de la pàgina «Pyramid: documentant amb Sphinx»
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…».) |
|||
| Línia 21: | Línia 21: | ||
# 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 src/egipcis on situarem l'arrel de la documentació.<pre>(env)$ cd src/egipcis</pre> | ||
| − | # Inicialitzem sphinx i responem amb els següents paràmetres:<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: . | ||
| + | #* Separar doc i arxius de codi: yes | ||
#* autodoc: yes | #* autodoc: 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 en "source":<pre>(env)$ sphinx-apidoc -o source/ 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 src/egipcis/build/html/index.html | ||
Revisió del 10:09, 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.
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 dels Egipcis per practicar i després fer-ho en el vostre.
- Descarregueu el projecte Egipcis de https://github.com/emieza/egipcis.git
- Aneu al directori src/egipcis on situarem l'arrel de la documentació.
(env)$ cd src/egipcis
- 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: .
- Separar doc i arxius de codi: yes
- autodoc: 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 source/ egipcis
- Crear la doc:
(env)$ make html
... i ja podem consultar-la amb el navegador a src/egipcis/build/html/index.html
