herramientas - documentar codigo en python
¿Puedo documentar el código de Python con doxygen(y tiene sentido)? (5)
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 / * .. * / comments y también tiene su propia función de auto-documentación que parece ser la manera pitónica de documentar.
¿Puedo usar doxygen? ¿Algo en especial para estar al tanto?
He hecho un poco de codificación en Python, pero hasta ahora solo en pequeños proyectos en los que era perezoso para documentar (sí, lo sé ... pero pretendemos que está bien por ahora).
Sphinx es principalmente una herramienta para formatear documentos escritos independientemente del código fuente, tal como lo entiendo.
Para generar documentos API de docstrings de Python, las herramientas principales son pdoc y pydoctor . Aquí están los documentos API generados por pydoctor para Twisted and Bazaar .
Por supuesto, si solo quiere echar un vistazo a los documentos mientras está trabajando en algo, existe la herramienta de línea de comandos " pydoc " y también la función de help() disponible en el intérprete interactivo.
Esto está documentado en el sitio web doxygen , pero para resumir aquí:
Puede usar doxygen para documentar su código Python. Puede usar la sintaxis de la cadena de documentación de Python:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
En este caso, doxygen extraerá los comentarios, pero no podrá usar ninguno de los comandos especiales de doxygen .
O bien, puede (similar a los lenguajes estilo C en doxygen) doblar 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 usar los comandos especiales de doxygen. No hay un modo de salida de Python en particular, pero aparentemente puede mejorar los resultados configurando OPTMIZE_OUTPUT_JAVA en YES .
Honestamente, estoy un poco sorprendido por la diferencia, parece que una vez que doxygen puede detectar los comentarios en ## bloques o "" "bloques, la mayor parte del trabajo estaría terminado y usted podría usar los comandos especiales en en ambos casos. ¿Tal vez esperan que las personas que usan "" "se adhieran a más prácticas de documentación de Pythonic y que interfieran con los comandos especiales de doxygen?
Otra herramienta de documentación muy buena es Sphinx . Se usará 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:
- Formatos de salida : HTML (incluida la Ayuda HTML de Windows) y LaTeX, para versiones PDF imprimibles
- Extensas referencias cruzadas : marcado semántico y enlaces automáticos para funciones, clases, términos del glosario y elementos similares de información
- Estructura jerárquica : definición fácil de un árbol de documentos, con enlaces automáticos a hermanos, padres e hijos
- Índices automáticos : índice general así como un índice de módulo
- Manejo de código : resaltado automático usando el resaltador Pygments
- Extensiones : prueba automática de fragmentos de código, inclusión de cadenas de documentos de módulos de Python y más
El filtro de entrada doxypy le permite usar casi todas las etiquetas de formato de Doxygen en un formato de docstring estándar de Python. Lo uso para documentar un gran marco mixto de aplicaciones de juegos de C ++ y Python, y está funcionando bien.
Al final, solo tienes dos opciones:
Generas tu contenido usando Doxygen o generas tu contenido usando Sphinx *.
Doxygen : no es la herramienta preferida para la mayoría de los proyectos de Python. Pero si tiene que tratar con otros proyectos relacionados escritos en C o C ++ podría tener sentido. Para esto puedes mejorar la integración entre Doxygen y Python usando doxypypy .
Sphinx : la herramienta de hecho para documentar un proyecto de Python. Aquí tiene tres opciones: manual, semiautomática (generación de stub) y totalmente automática (similar a Doxygen).
- Para la documentación manual de la API tiene Sphinx autodoc . Esto es excelente para escribir una guía de usuario con elementos generados API incorporados.
- Para semiautomático tiene Sphinx autosummary . Puede configurar su sistema de compilación para llamar a sphinx-autogen o configurar su Sphinx con la configuración
autosummary_generate. Necesitará configurar una página con autosummaries y luego editar manualmente las páginas. Tienes 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é fue lo que se expuso como API pública y qué no. Mi opinión es que esta herramienta es buena para la generación de stubs que requerirá edición manual, y nada más. Es como un atajo para terminar en manual. - Completamente automatico. Esto ha sido criticado muchas veces y durante mucho tiempo no tuvimos un buen generador de API Python completamente automático integrado con Sphinx hasta que llegó AutoAPI , que es un chico nuevo en el bloque. Este es de lejos el mejor para la generación automática de API en Python (nota: autopromoción desvergonzada).
Hay otras opciones para tener en cuenta:
- Respire : esto comenzó como una muy buena idea, y tiene sentido cuando trabajas con varios proyectos relacionados en otros idiomas que usan Doxygen. La idea es usar la salida Doxygen XML y alimentarla a Sphinx para generar su API. Por lo tanto, puede mantener todas las bondades de Doxygen y unificar el sistema de documentación en Sphinx. Impresionante en teoría. Ahora, en la práctica, la última vez que revisé el proyecto no estaba listo para la producción.
- pideoctor *: muy particular. Genera su propio resultado Tiene una integración básica con Sphinx y algunas características agradables.