[pyar] Documentar API de una biblioteca (¿automáticamente?)

[Martín Gaitán]

2015-06-02 16:03 GMT-03:00 Hugo Ruscitti <hugoruscitti en gmail.com>:

> Saludos, estoy queriendo publicar la documentación de una biblioteca que
> estoy haciendo pero de forma automática, ¿conocen alguna herramienta para
> hacer eso?, algo que me arme una listado de clases, métodos y docstrings.
>
> Estuve viendo epydoc y otras cosas como sphinx, pero me gustaría algo mas
> "moderno" (¿?).
>
> ¿o me conviene hacer un script que extraiga toda esa data en un formato
> sencillo tipo json o rst?, ¿alguno hizo algo así? ;)
>
>
El tema es primero filosófico y luego tecnológico. ¿es la autodocumentación
de una API suficiente documentación?

Sphinx es capaz de documentar APIs haciendo instrospección de código [1]
(incluso de software no python [2]) , pero está planteado para que eso sea
*sólo parte* de la documentacion (usando la extension "autodoc" [1], puesta
en el contexto de un desarrollo mas completo que implica *escribir
documentación*

Un gran articulo (parte de una serie) sobre este tema es de Kaplan Moss [3]
(uno de los creadores de Django):

"...It’s really tempting to use an auto-documentation tool like Javadoc or
RDoc for reference material. Don’t. Auto-generated documentation is almost
worthless. "

[1] http://sphinx-doc.org/ext/autodoc.html
[2] http://breathe.readthedocs.org/en/latest/
[3] https://jacobian.org/writing/what-to-write/

Pero si preferís no darle bola, se puede automatizar aún la generacion de
los fuentes que usen "autodoc" con este script.

http://sphinx-doc.org/man/sphinx-apidoc.html

Por otro lado, la gente de Django-rest-framework liberó hace poco Mkdocs,
que usa markdown en vez de rest

http://www.mkdocs.org/

Readthedocs.org lo soporta como "compilador" de doc alternativo a sphinx

dos recursos más:

- los slides di una charla en un pyday sobre documentación (se ven muy
feos, no sé bien por qué)

http://mgaitan.github.io/charla__doc__/presentacion.html

- y la doc the writethedocs.org

http://docs.writethedocs.org

abrazo!
------------ próxima parte ------------
Se ha borrado un adjunto en formato HTML...
URL: <http://listas.python.org.ar/pipermail/pyar/attachments/20150602/134a9f63/attachment.html>