Cómo documentar el código Python con doxygen [cerrado]

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 autodocumentación que parece ser la forma 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

Esto es documentado en el sitio web de doxygen, pero para resumir aquí:

Puede utilizar 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ás utilizar ninguno de los comandos especiales de doxygen.

O puedes (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, puedes utilizar los comandos especiales de doxygen.No existe un modo de salida de Python en particular, pero aparentemente puedes mejorar los resultados configurando OPTMIZE_OUTPUT_JAVA a 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á hecho y podrás usar los comandos especiales en cualquier caso.¿Quizás esperan que las personas que usan """ se adhieran a más prácticas de documentación de Pythonic y eso interferiría con los comandos especiales de doxygen?

Answer 2

El doxypy El filtro de entrada le permite utilizar prácticamente todas las etiquetas de formato de Doxygen en un formato de cadena de documentación estándar de Python.Lo uso para documentar un gran marco de aplicación de juegos mixto de C++ y Python, y está funcionando bien.

Answer 3

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 Retorcido y Bazar.

Por supuesto, si solo quieres echar un vistazo a las cadenas de documentación mientras trabajas en cosas, está la opción "pydoc"herramienta de línea de comando y además de la help() Función disponible en el intérprete interactivo.

Answer 4

Al final sólo te quedan dos opciones:

Usted genera su contenido usando Doxygen, o genera su contenido usando Sphinx*.

1. doxigeno:No es la herramienta elegida para la mayoría de los proyectos de Python.Pero si tienes que lidiar 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.

2. Esfinge:La herramienta de facto para documentar un proyecto de Python.Tienes tres opciones aquí:manual, semiautomático (generación de trozos) y completamente automático (similar a Doxygen).

   1. Para la documentación API manual tienes Sphinx autodoc.Es fantástico escribir una guía de usuario con elementos generados por API integrados.
   2. Para semiautomático tienes Sphinx. autoresumen.Puede configurar su sistema de compilación para llamar a sphinx-autogen o configurar su Sphinx con el autosummary_generate configuración.Deberá configurar una página con los resúmenes automáticos 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é se expuso como API pública y qué no.Mi opinión es que esta herramienta es buena para la generación de códigos auxiliares que requerirán 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 API automática vino, que es un chico nuevo en el bloque.Este es, con diferencia, 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 comenzó 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.Entonces, puedes 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é que el proyecto no estaba listo para producción.
• pydoctor*:Muy particular.Genera su propia salida.Tiene cierta integración básica con Sphinx y algunas características interesantes.

Answer 5

Otra muy buena herramienta de documentación es esfinge.Se utilizará para el próximo Python 2.6. documentación y es utilizado por Django y muchos otros proyectos de Python.

Del sitio web de la esfinge:

• Formatos de salida:HTML (incluida la Ayuda HTML de Windows) y LaTeX, para versiones PDF imprimibles
• Amplias referencias cruzadas:marcado semántico y enlaces automáticos para funciones, clases, términos del glosario e información similar
• Estructura jerarquica:Fácil definición 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:pruebas automáticas de fragmentos de código, inclusión de cadenas de documentación de módulos de Python y más