Cómo documentar el código de Python con doxygen

Question

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 manera pitónica de documentar.

Como estoy familiarizado con doxygen, ¿cómo puedo usarlo para producir mi documentación de Python? ¿Hay algo en particular que deba tener en cuenta?

Answer 1

Ésta es documented on the doxygen website, pero para resumir aquí:

Puede utilizar doxygen para documentar su código Python. También se puede usar 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 usted no será capaz de utilizar cualquiera de los special doxygen commands.

O puede (similar a los lenguajes de tipo C bajo doxygen) doblar el marcador de comentario (#) en la primera línea antes de que el miembro de:

## @package pyexample 
# Documentation for this module. 
# 
# More details. 

## Documentation for a function. 
# 
# More details. 
def func(): 
    pass 

En ese caso, se puede utilizar el comandos doxygen especiales. 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 sería capaz de usar los comandos especiales 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?

Answer 2

Otra herramienta de documentación muy buena es sphinx. Se usará para el próximo pitón 2.6 documentation y es utilizado por django y muchos otros proyectos de python.

Desde la página web de la esfinge:

• Los formatos de salida: HTML (incluyendo Windows HTML Help) y LaTeX, para las versiones imprimibles PDF
• extensas referencias cruzadas: el marcado semántico y enlaces automáticos para funciones, clases, términos del glosario y datos similares
• Estructura jerárquica: fácil definición de un árbol de documentos, con enlaces automáticos a sibli NGS, los padres y los niños
• índices automáticos: índice general, así como un índice de módulos
• manejo Código: resaltado automático utilizando el Pygments highlighter
• Extensiones: prueba automática de fragmentos de código, la inclusión de docstrings de módulos Python, y más

Answer 3

Sphinx es principalmente una herramienta para formatear documentos escritos independientemente del código fuente, según tengo entendido.

Para generar documentos API de cadenas 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 quiere echar un vistazo a los documentos mientras trabaja en cosas, existe la herramienta de línea de comandos "pydoc" y la función help() disponible en el intérprete interactivo.

Answer 4

El filtro de entrada doxypy le permite usar prácticamente 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.

Answer 5

Al final, sólo tiene dos opciones:

de generar el contenido usando Doxygen, o generar su contenido usando Sphinx *.

1. Doxygen: No es la herramienta de elección 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 puede mejorar la integración entre Doxygen y Python usando doxypypy.

2. 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).

   1. Para la documentación de la API manual tiene Sphinx autodoc. Esto es excelente para escribir una guía de usuario con elementos generados API incorporados.
   2. 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. Tendrá que configurar una página con las autosummias y luego editar las páginas manualmente. 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.
   3. Totalmente automático. 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 a tener en cuenta:

• Breathe: esto comenzó como una muy buena idea, y tiene sentido cuando se trabaja con varios proyectos relacionados en otros idiomas que utilizan 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.
• pydoctor *: Muy particular. Genera su propio resultado Tiene una integración básica con Sphinx y algunas características agradables.