Me gusta Doxygen para crear documentación de código C o PHP. Tengo un próximo proyecto de Python y creo recordar que Python no tiene /* .. */comentarios, y también tiene su propia función de auto-documentación que parece ser la forma pitónica de documentar.
Dado que estoy familiarizado con Doxygen, ¿cómo puedo usarlo para producir mi documentación de Python? ¿Hay algo en particular que deba tener en cuenta?
Respuestas:
Esto está documentado en el sitio web de doxygen , pero para resumir aquí:
Puede usar doxygen para documentar su código Python. Puede utilizar la sintaxis de cadena de documentación de Python:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
En cuyo caso, los comentarios serán extraídos por doxygen, pero no podrá usar ninguno de los comandos especiales de doxygen .
O puede (similar a los lenguajes de estilo C en doxygen) duplicar el marcador de comentario ( #) en la primera línea antes del miembro:
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
En ese caso, puede utilizar los comandos especiales de doxygen. No hay un modo de salida de Python en particular, pero aparentemente puede mejorar los resultados estableciendo OPTMIZE_OUTPUT_JAVAen YES.
Honestamente, estoy un poco sorprendido por la diferencia: parece que una vez que doxygen pueda detectar los comentarios en ## bloques o bloques "" ", la mayor parte del trabajo estaría hecho y usted podría usar los comandos especiales en En cualquier caso. ¿Quizás esperan que la gente que usa "" "se adhiera a más prácticas de documentación Pythonic y eso interferiría con los comandos especiales de doxygen?
El filtro de entrada doxypy le permite usar prácticamente todas las etiquetas de formato de Doxygen en un formato de cadena de documentos estándar de Python. Lo uso para documentar un gran marco mixto de aplicaciones de juegos C ++ y Python, y está funcionando bien.
Al final, solo tienes dos opciones:
Genera su contenido usando Doxygen, o genera su contenido usando Sphinx *.
Doxygen : no es la herramienta elegida para la mayoría de los proyectos de Python. Pero si tiene que lidiar con otros proyectos relacionados escritos en C o C ++, podría tener sentido. Para ello, puede mejorar la integración entre Doxygen y Python usando doxypypy .
Esfinge : la herramienta de facto para documentar un proyecto de Python. Tiene tres opciones aquí: manual, semiautomático (generación de stub) y completamente automático (como Doxygen).
autosummary_generateconfig. Deberá configurar una página con los resúmenes automáticos y luego editar manualmente las páginas. Tiene opciones, pero mi experiencia con este enfoque es que requiere demasiada configuración y, al final, incluso después de crear nuevas plantillas, encontré errores y la imposibilidad de determinar exactamente qué se expuso como API pública y qué no. Mi opinión es que esta herramienta es buena para la generación de stub que requerirá edición manual y nada más. Es como un atajo para terminar en manual.Hay otras opciones a tener en cuenta:
__all__variable explicite.
Sphinx es principalmente una herramienta para formatear documentos escritos independientemente del código fuente, según tengo entendido.
Para generar documentos API a partir de cadenas de documentos de Python, las herramientas principales son pdoc y pydoctor . Aquí están los documentos API generados por pydoctor para Twisted y Bazaar .
Por supuesto, si solo desea echar un vistazo a las cadenas de documentos mientras trabaja en cosas, existe la herramienta de línea de comandos " pydoc " y también la help()función disponible en el intérprete interactivo.
Otra muy buena herramienta de documentación es Sphinx . Se utilizará para la próxima documentación de python 2.6 y es utilizado por django y muchos otros proyectos de Python.
Desde el sitio web de la esfinge: