Cómo documentar el código de Python: Epydoc, doxygen, Sphinx, ...?

Question

No estoy seguro de si debería usar Epydoc o doxygen para documentar mi código Python. Actualmente preferiría Epydoc ya que está especializado en Python y su sintaxis no es muy diferente de la de doxygen (que he usado para documentar mi código C/C++ hasta ahora).

¿Algún argumento en contra de Epydoc o para usar doxygen?

• http://epydoc.sourceforge.net/
• http://www.doxygen.org/
• http://sphinx.pocoo.org/

Answer 1

Epydoc había sido la herramienta clásica para la generación de documentos. Sin embargo, últimamente todos se están mudando a esfinge.

Debe usar epydoc o puede intentar usar sphinx. La documentación de Python se hace usando sphinx. Sphinx puede proporcionarle más control y una mejor documentación.

• http://sphinx-doc.org/

No hay nada malo con doxygen sino que proporciona una gran cantidad de beneficios para C/C++ programas. Como existen herramientas de documentación especializadas para el código python, pueden proporcionarle un mejor control sobre la generación de documentos.

Answer 2

Probé Sphinx, epydoc y doxygen para mi proyecto python.

Sphinx no funcionó para mí, ya que depende de poder importar cada módulo. Aunque mi proyecto funciona bien y Sphinx pudo encontrar sus módulos, la Sphinx no pudo importar la mayoría de los módulos. Sphinx puede ser útil para la documentación general y para crear un manual del usuario, pero al menos para documentar mi código fuente es inútil. Parece que para Sphinx el módulo debe poder funcionar solo. Pero en mi proyecto, el primer módulo intenta conectarse a una base de datos. Si la conexión de la base de datos falla, se detiene. Muchos de los otros módulos esperan un cursor de base de datos. Si no se estableció la conexión de la base de datos, no se pueden importar y, por lo tanto, Sphinx falla.

Doxygen funcionó bien. Si se combina con doxypy, es aún mejor. Sin embargo, tiene algunos inconvenientes. Si desea una lista numerada en el código fuente, no la encontrará en la documentación y viceversa. Además, si lee la documentación, la fuente no está visible.

Así que probé Epydoc. A pesar de que Epydoc no se actualizó por más de 3 años y, por lo tanto, murió, para mí fue la mejor herramienta para documentar el código python. Epydoc, al igual que Sphinx, intenta importar cada módulo, PERO si la importación falla, solo muestra un mensaje de error y luego intenta analizar el módulo, como lo hace doxygen. La documentación generada por Epydoc es agradable y tiene algunas ventajas sobre doxygen: 1. La fuente que está documentada puede hacerse visible con solo un clic. 2. Las listas numeradas en una docstring están numeradas en la documentación también.

La instalación de Sphinx es bastante complicada si easy_install con conexión a Internet no se puede utilizar. Esto se debe a que Sphinx depende de otros paquetes. Doxygen se puede instalar tan fácil como la mayoría de los programas que vienen con un instalador de un clic. Pero DoxyPy y puede ser gaphviz también debería estar instalado. Expydoc también se puede instalar con solo un clic, pero en Windows 7 esto debe hacerse explícitamente como administrador, mientras que el instalador de Epydoc no comprueba si se inició con suficientes derechos. Obtener la primera documentación utilizable de mi proyecto fue de lejos la más fácil y rápida con Epydoc. Finalmente, todavía se puede recomendar Epydoc como la mejor herramienta para documentar proyectos Python. Sphinx puede ser una buena herramienta para producir la documentación del usuario.