docstrings pitón estructurados, IDE-amigable

Question

En PHP que estaba acostumbrado a la sintaxis PHPdoc:

/** Do something useful
@param first    Primary data
@return int
@throws BadException
*/
function($first){ ...

- Referencia poco corto útil: muy práctico cuando todo lo que necesita es sólo para recordar '¿qué es eso ??', especialmente para las bibliotecas 3 ª parte. Además, todos los entornos de desarrollo pueden mostrar esto en consejos emergentes.

Parece que no hay convenciones en Python: solo texto plano. En él se describen las cosas bien, pero es demasiado largo para ser un digesto.

Ok, deja que sea. Pero en mis aplicaciones no quiero utilizar pilas de texto plano.

¿Hay convenciones conocidas a seguir? Y la forma de documentar los atributos de clase ?! PyCharm IDE recetas son especialmente bienvenidos:)

---

En python3 hay un PEP 3107 para las anotaciones funcionales . Eso no es útil para 2.x (2.6, específicamente)

También hay un PEP 0287 para reStructuredText: suposición, pero todavía no estructurado .

Answer 1

El numpydoc estándar está bien definido, en torno a reStructuredText ( que es estándar en el ecosistema pitón), y tiene integración Sphinx. Debería ser relativamente sencillo para escribir un plugin para PyCharm que puede digerir numpydoc.

Sphinx también tiene referencias sobre la forma de atributos de los documentos: http: // esfinge. pocoo.org/ext/autodoc.html?highlight=autoattribute

Answer 2

epydoc . Es compatible con los comentarios de texto reStructured, y genera documentación HTML de estas últimas (similar a javadoc).