Migración de Javadoc a la documentación de Python

Question

Me he acostumbrado a la documentación de estilo de Javadoc. Mirando a través de varios ejemplos de código de Python, estoy descubriendo que, a primera vista, la documentación parece por lo que falta mucha información.

Lo bueno: varía rara vez ves trozos evidentes de documentación. Las cadenas de documentos suelen ser un párrafo o menos de marcado en inglés que se integra en lugar de sobresalir en líneas separadas.

Lo malo: junto con el tipado de pato de Python, encuentro que muchas funciones no están claras acerca de los parámetros que esperan. No hay ninguna sugerencia de tipo (¿insinuación de pato?) Y muchas veces sería bueno tener una idea de que el parámetro debería ser similar a una lista, similar a una cadena, similar a una secuencia.

Por supuesto, Javadoc fue diseñado para un lenguaje de bajo nivel, sin grandes habilidades de introspección de Python, lo que podría explicar la filosofía de documentación menos detallada.

¿Algún consejo sobre los estándares de documentación de Python y las mejores prácticas?

Answer 1

El formato reStructuredText fue diseñado en respuesta a la necesidad de documentación de Python que podrían ser incrustado en las cadenas de documentación, así que lo mejor es aprender a el descanso y el formato a su docstrings con ese formato. Usted puede encontrar, como yo, que luego pasan a formato de casi cualquier documentación en el descanso, pero eso es un punto de lado :-)

Para documentar específicamente su código Python, el sistema Sphinx es un conjunto de extensiones para el formato reST y un sistema de compilación para renderizar documentos. Dado que fue diseñado para documentar Python en sí, incluida la biblioteca estándar, Sphinx permite una documentación muy bien estructurada del código fuente, que incluye, por supuesto, los detalles de las firmas de función cuando usted pregunta. Permite la creación de un conjunto completo de documentación, tanto autoextraíble como manuscrita, todo ello utilizando el mismo sistema de formato.

Si solamente quieren la documentación generada a partir de su código fuente, entonces Epydoc extraerá documentación de la API a partir del código fuente; también lee el formato reST para el texto.