Compartiendo documentación de paquetes python
Sabido es, aunque muchas veces se ignora, que un software sin documentación está incompleto [1].
Si bien el manifiesto ágil proclama "Software funcionando sobre documentación extensiva", yo subrayaría extensiva como eufemismo de documentación burocrática e inútil (opiné de esto acá) que evidentemente no es la que hace falta. Pero la documentación (sobre todo la buena) es indispensable y para algunos, la parte que más los enorgullece del proyecto (y con razón).
Desde el punto de vista técnico, escribir documentación (no sólo para Python!) es bastante fácil con restructuredText (qué feo el sitio de docutils, che!) que es el markup estándar de los pythonistas.
Sobre este markup funciona Sphinx, el generador de documentación más utilizado (por lejos) en el ecosistema de Python. Es lo que usa la documentación de Python misma, la de Django y casi todo proyecto conocido o por conocer.
Entonces usamos restructuredText, usamos Sphinx, pero para nuestro proyectito de morondanga que no tiene web propia ni nada, ¿dónde subimos la documentación generada? Veamos.
Usando Readthedocs.org
Read the docs es un sitio para hospedar documentación realizada con Sphinx. Sólo se necesita indicarle el repositorio público del proyecto (svn, git, mercurial, bazaar), subir los fuentes .rst y contenido estático (imágenes) aptos para Sphinx en una carpeta /doc o /docs y el sitio se encarga de bajar los fuentes de documentación y renderizarlos a HTML a través de Sphinx.
Estrictamente, usando rtfd.org (como le dicen los amigos) ni siquiera hace falta tener Sphinx instalado localmente.
System Message: WARNING/2 (<string>, line 31); backlink
Duplicate explicit target name: "acá".
Más aun, por defecto actualiza diariamente, pero se puede utilizar un "hook" para indicarle que actulice cuando "pusheamos" (o "commiteamos") al repo, de manera de tener la documentación actualizada al instante. Para usuarios de GitHub la activación del "web hook" se explica acá . Para BitBucket.org es parecido:
Vas a tu proyecto , click en Admin -> Services
Agregás el servicio "POST"
Completás el campo de texto con la URL que te da ReadTheDocs en la página de descripción de tu proyecto (estándo logueado). Por ejemplo:
System Message: WARNING/2 (<string>, line 60)
Explicit markup ends without a blank line; unexpected unindent.
Y listo. Tu docu al instante.
Como el sitio genera el html en vez de servir una versión generada
previamente, la documentación que requiere introspección del código (
todas las directivas `` .. auto* :: `` de Sphinx) este debe poder
ejecutarse. Para eso el paquete debe ser instalable via setup.py y
hay marcar desde la página de configuración del proyecto en RTFD.org,
que instale en un virtualenv.
Para ver si hubo algún problema en la generación, podés fijarte en "build" donde te muestra el stdout y el stderr de la corrida de Sphinx.
Subir la docu a PyPi
Una forma buenísima de compartir tu trabajo pythónico es a través del
Python Package Index, pypi, que es el
índice que usan las herramientas pip e
easy_install. Si bien no necesarimente los paquetes deben estar
hospedados allí (indicando en el setup.py la URL de descarga) es muy
común y fácil hacerlo con el comando upload del setup.py.
Lo que muchos no saben es que PyPi también ofrece hostear la documentación. La forma canónica es ir a la página de administración de tu proyecto en PyPi y adjuntar un .zip con la documentación (que no necesariamente tiene que ser hecha con Sphinx)
System Message: WARNING/2 (<string>, line 93)
Explicit markup ends without a blank line; unexpected unindent.
Pero si usamos Sphinx hay una manera más fácil, manteniendosé en el "ecosistema" de desarrollo: usar esta extension de setuptools que permite generar el html a través Sphinx y subirlo automáticamente. Se instala, obviamente, vía pypi:
$ easy_install sphinx-pypi-upload
Hay que condigurar un setup.cfg (ubicado al nivel raiz, junto con
setup.py) indicandole dónde está la docu fuente y dónde el
resultado. Más o menos así:
[build_sphinx] source-dir = doc/source build-dir = doc/build all_files = 1 [upload_sphinx] upload-dir = doc/build/html
Luego se usa:
$ python setup.py build_sphinx $ python setup.py upload_sphinx
Y docu subida a la dire `http://packages.python.org/tu-proyecto <http://packages.python.org/tu-proyecto>`_ . ¡Charaaán!
Usando tu repositorio SVN
Si usas SVN y tu servidor lo permite, podés servir contenido estático (html y todo lo que produce y necesita Sphinx) directamente desde el repositorio.
Para que el servidor Subversion muestre el html renderizado en vez del
código (como texto plano) hay que indicarle el tipo mime de cada
archivo.
$ svn propset svn:mime-type 'text/html' FILENAME $ svn propset svn:mime-type 'image/jpeg' FILENAME
Para que esto se haga automático, se puede modificar el archivo de configuración ``~/.subversion/config ``
System Message: WARNING/2 (<string>, line 144); backlink
Inline literal start-string without end-string.
[miscellany] enable-auto-props = yes [auto-props] *.html = svn:mime-type=text/html *.css = svn:mime-type=text/css *.js = svn:mime-type=text/javascript *.png = svn:mime-type=image/png *.jpg = svn:mime-type=image/jpeg *.gif = svn:mime-type=image/gif
Un ejemplo de esto es el reporte de mi proyecto integrador que está hospedado en Google Code
Aprovechándote de GitHub
GitHub hospeda páginas estáticas, tanto del desarrollador/a como de tus proyectos. Bien sirve eso para subir la documentación y eso hacen mas o menos automáticamente estas opciones que no he probado pero las dejo como referencia:
Hosting sphinx doc in
github
de Luca Sbardella.
Usando
github-tools.
Comentarios
Comments powered by Disqus