Parece que hay una gran cantidad de herramientas de documentación para Python. Otro con el que me he encontrado es epydoc. Parece que Sphinx es el estándar de facto, porque se usa para generar los documentos oficiales de Python. ¿Alguien puede por favor resolver el estado actual de las herramientas de documentación de Python?¿Cuál es la relación entre docutils y Sphinx?
epydoc y Sphinx son diferentes tipos de herramientas.
Ellos son los mismos en cuanto a que:
Ellos son diferentes en su enfoque.
Por lo tanto, depende de la cantidad de trabajo que desee realizar y de lo que esté documentando.
Gracias por explicar lo que estas herramientas tienen en común (por ejemplo, su relación con los docorados), así como sus diferencias. ¿Qué mejora epydoc para la documentación API y Sphinx mejor para la documentación funcional? Usted mencionó que ambos usan reST. Parece que hay muchas superposiciones. ¿Es solo una cuestión de conveniencia? Además, el desarrollo de epydoc no parece ser muy activo. El último compromiso fue en febrero de 2009, y la última correspondencia en la lista de desarrollo fue en mayo de 2009. – allyourcode
Bueno, la respuesta fácil a por qué uno es mejor en una cosa que otra es que es la forma en que fueron diseñados. Epydoc está hecho para extraer del código y Sphinx está hecho para generar gran parte de su documentación a partir de los archivos ReST que usted escribe. Hay mucha superposición. Sphinx es el nuevo chico en el bloque. He escuchado rumores de que en .7 tendrá mucha mejor generación de autogeneración. Tengo mucho respeto por Epydoc, pero Sphinx parece tener todo el impulso en este momento. Me gusta porque se parece a la documentación de python.org Y creo que se ve mejor. –
Sphinx no se centra en la documentación general del usuario. Sphinx es una herramienta que le ayuda a escribir una documentación completa y detallada, que simplemente no puede proporcionar mediante la concatenación de documentos. También Sphinx soportará los denominados dominios con 1.0 que le permitirán documentar un proyecto escrito en múltiples idiomas, por ejemplo, una aplicación web escrita en Python, Javascript y C. – DasIch
Parece que Epydoc es, si no está muerto, al menos pining para los fiordos.
Sphynx con el comando sphinx-apidoc y la extensión autodoc parece ser la opción más popular para los documentos API en este momento.
Buenos ejemplos son:
Ver: Should we use Epydoc, Sphinx or something else for documenting Python APIs? (SO5579198)
Sphinx fomenta un estilo más narrativo que las herramientas en el molde javadoc , pero tal vez esto es algo bueno?
Hace poco cambié de Python2 a Python3 y encontré que no había ningún paquete de Epydoc para Python3. Parece que con Python3 hay un claro enfoque en el uso de Sphinx como documentación API.
¿Estado actual? Qué significa eso? ¿Se puede ampliar al respecto? Sphinx requiere docutils; epydoc puede usar la misma notación RST. ¿Que quieres saber? ¿Puedes ser mas específico? –
por ejemplo, ¿qué herramientas tienen un fuerte apoyo de la comunidad, desarrollo activo? ¿Existe una solución establecida, o hay muchas sin ninguna que tenga un seguimiento significativamente mayor? – allyourcode
Tal vez deberías editar el título de esta pregunta. –