¿Cuál es la relación entre docutils y Esfinge?

Question

Parece que hay una gran cantidad de herramientas de documentación de Python. Otro que me he encontrado a través es epydoc. Parece que la esfinge es el estándar de facto, porque se usa para generar la documentación oficial de Python. Por favor alguien puede resolver la situación actual de herramientas de documentación de Python para mí?

Answer 1

epydoc y Esfinge son diferentes tipos de herramientas.

Se trata de la misma en cuanto a que:

• Tanto uso ReST vía docutils .
• Ambos son muy Pythonic en su enfoque
• Ambos pueden generar documentación HTML y PDF

Son diferentes en su enfoque.

• Epydoc se centra en la documentación API (desarrollador). Usted obtiene más resultados más rápido con Epydoc. La que apunte a su código fuente y se obtiene algo. Esto es lo que quiero de una herramienta de documentación de la API.
• Esfinge se centra en la documentación general (Usuario). Mientras Sphinx hace tirar de una gran cantidad de información de su código fuente que necesita para poner un poco más en ella. Sphinx puede generar documentación de la API, pero no es tan sencillo, y la OMI no hacer tan bien de un trabajo como Epydoc. Sé que algunos no estarán de acuerdo porque Esfinge se elige para Python . PERO, que depende de la cantidad de trabajo que desea poner en él. Me encanta Esfinge de documentación general.

Así que depende de la cantidad de trabajo que desea poner en él y lo que se está documentando.

Answer 2

Recientemente he cambiado de python2 a python3 y se encontró que no había ningún paquete de Epydoc python3. Por lo que parece, con python3 hay un claro enfoque en el uso de la esfinge como documentación de la API.

Answer 3

Parece que Epydoc es, si no muerto, al menos suspirando por los fiordos.

Sphynx con la comando Sphinx-apidoc y la autodoc extensión parece ser la opción más popular para los documentos de la API en este momento.

Los buenos ejemplos son:

• solicitudes ( src )
• boto ( src )

Ver: Deberíamos usar Epydoc, Sphinx o alguna otra cosa para la documentación de las API de Python? (SO5579198)

Esfinge fomenta un estilo más narrativo que las herramientas en el molde javadoc, pero tal vez esto es una buena cosa?