Structured python docstrings, IDE-friendly

Question

In PHP I was used to PHPdoc syntax:

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

— kinda short useful reference: very handy when all you need is just to recall 'what's that??', especially for 3rd-party libraries. Also, all IDEs can display this in popup hints.

It seems like there's no conventions in Python: just plain text. It describes things well, but it's too long to be a digest.

Ok, let it be. But in my applications I don't want to use piles of plaintext.

Are there any well-known conventions to follow? And how to document class attributes?! PyCharm IDE recipes are especially welcome :)

---

In Python3 there's a PEP 3107 for functional annotations. That's not useful for 2.x (2.6, specifically)

Also there's a PEP 0287 for reStructuredText: fancy but still not structured.

Answer 1

The numpydoc standard is well-defined, based around reStructuredText (which is standard within the python ecosystem), and has Sphinx integration. It should be relatively straight forward to write a plugin for PyCharm which can digest numpydoc.

Sphinx also has references on how to document attributes: http://sphinx.pocoo.org/ext/autodoc.html?highlight=autoattribute

Answer 2

I use epydoc. It supports comments in reStructured Text, and it generates HTML documentation from those comments (akin to javadoc).