how - sphinx python example

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

Question

Parece que hay una gran cantidad de herramientas de documentación para Python. Otro que he encontrado es epydoc. Parece que Sphinx es el estándar de facto, porque se utiliza para generar los documentos oficiales de Python. ¿Alguien puede ordenar el estado actual de las herramientas de documentación de Python para mí?

Answer 1

Parece que epydoc es, si no muerto, al menos en busca de los fiordos.

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

Buenos ejemplos son:

• requests ( src )
• boto ( src )

Ver: ¿Deberíamos usar Epydoc, Sphinx o algo más para documentar las API de Python? (SO5579198)

Sphinx fomenta un estilo más narrativo que las herramientas en el molde javadoc, pero ¿quizás esto es algo bueno?

Answer 2

Recientemente cambié de Python2 a Python3 y descubrí que no había un paquete Epydoc para Python3. Así que parece que con Python3 hay un claro enfoque en el uso de Sphinx como documentación de API.

Answer 3

epydoc y Sphinx son diferentes tipos de herramientas.

Son los mismos en que ellos:

• Ambos utilizan ReST través de docutils .
• Ambos son muy pitónicos en su enfoque.
• Ambos pueden generar documentación HTML y PDF.

Son diferentes en su enfoque.

• Epydoc se centra en la documentación de la API (desarrollador). Obtienes más resultados más rápido con Epydoc. Lo apuntas a tu código fuente y obtienes algo. Esto es lo que quiero de una herramienta de documentación API.
• Sphinx se centra en la documentación general (Usuario). Si bien Sphinx obtiene mucha información de su código fuente, necesita poner un poco más en ella. Sphinx puede generar documentación de API, pero no es tan sencillo, y IMO no hace un trabajo tan bueno como Epydoc. Sé que algunos no estarán de acuerdo porque Sphinx es elegido para Python . PERO, depende de la cantidad de trabajo que desee poner en él. Me encanta Sphinx para la documentación general.

Entonces, depende de la cantidad de trabajo que desee poner en él y de lo que está documentando.