Pyramid: documentant amb Sphinx

De Cacauet Wiki
La revisió el 10:06, 30 abr 2013 per Enric (discussió | contribucions) (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…».)
(dif) ← Versió més antiga | Versió actual (dif) | Versió més nova → (dif)
Salta a la navegació Salta a la cerca

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:

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 . .
  • 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.

  1. Descarregueu el projecte Egipcis de https://github.com/emieza/egipcis.git
  2. Aneu al directori src/egipcis on situarem l'arrel de la documentació.
    (env)$ cd src/egipcis
  3. Inicialitzem sphinx i responem amb els següents paràmetres:
    (env)$ sphinx-quickstart
    • Directori per la doc: .
    • autodoc: yes
    • Separar doc i arxius de codi: yes
    • Crear links al codi dins la doc: yes
  4. Crear arxius .rst automàticament. Agafa les fonts de "egipcis" i guarda els .rst en "source":
    (env)$ sphinx-apidoc -o source/ egipcis
  5. Crear la doc:
    (env)$ make html

... i ja podem consultar-la amb el navegador a src/egipcis/build/html/index.html