Cómo documentar código Python usando Doxygen [cerrado]

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?

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 *.

1. 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 .

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

   1. Para la documentación manual de la API, tiene Sphinx autodoc . Es genial escribir una guía de usuario con elementos generados por API integrados.
   2. Para semiautomático, tiene el resumen automático de Sphinx . Puede configurar su sistema de compilación para llamar a sphinx-autogen o configurar su Sphinx con el archivo 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.
   3. Completamente automatico. Esto ha sido criticado muchas veces y durante mucho tiempo no tuvimos un buen generador de API de Python completamente automático integrado con Sphinx hasta que llegó AutoAPI , que es un niño nuevo en el bloque. Este es, con mucho, el mejor para la generación automática de API en Python (nota: autopromoción descarada).

Hay otras opciones a tener en cuenta:

• Respirar : esto empezó como una muy buena idea y tiene sentido cuando trabajas con varios proyectos relacionados en otros lenguajes que usan Doxygen. La idea es utilizar la salida XML de Doxygen y enviarla a Sphinx para generar su API. Por lo tanto, puede conservar 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 verifiqué el proyecto no estaba listo para la producción.
• pydoctor *: Muy particular. Genera su propia salida. Tiene una integración básica con Sphinx y algunas características interesantes.

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:

• Formatos de salida : HTML (incluida la Ayuda HTML de Windows) y LaTeX, para versiones imprimibles en PDF
• Referencias cruzadas extensas : marcado semántico y enlaces automáticos para funciones, clases, términos del glosario y piezas de información similares
• Estructura jerárquica : definición sencilla de un árbol de documentos, con enlaces automáticos a hermanos, padres e hijos
• Índices automáticos : índice general así como índice de módulo
• Manejo de código : resaltado automático con 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