Python documentation

[Sven Brauch]

Hi!

I'd like to have inline documentation for python modules, and the ones in
your current project. Now, there's a tool called pydoc which creates nice
HTML documentation which is also quite suitable to be displayed in the
tooltips; looks like this: http://i.imgur.com/medlL.png
But: It's slow, and it does not have a cache. For example, if I ask for the
documentation for the "random" module, it'll take about half a second to
generate that, and it doesn't have a cache. And that module isn't really
very large...
Plus, I'd also need documentation for custom modules, which will probably be
updated frequently.

So I could use files to cache this data, but I don't really like that idea,
because they aren't really well queryable, and it's quite some effort to
safely and reliably create and name them. What do you think about using a
SQLite database for this? There could be a pre-computed database with
documentation for standard modules, and a low-priority documentation worker
could be created whenever a custom file is updated.
I'm not sure about this because a) it means the plugin would depend on
SQLite (which is probably not *that* bad) but b) the documentation is
completely detached from the kdevplatform classes. I'm not sure how screwy
b) is, especially as kdevplatform seems to have some pretty advanced
documentation management classes already. And, i'd need to extract
information like parameters via Regex matching or similar methods. Or
customize pydoc to output them seperately (it's easy to modify, as it's
written in python).

The alternative would be to create some preprocessed python files which
contain pseudocode for the modules and parse them into a DUChain, similar to
what the php plugin currently does with it's internal functions file. But
this will probably be even slower, and it's more effort to write, and also
crappy (because pydoc won't generate that kind of output format by itself).

Also, for the database solution, documentation for modules which are not
well documented in pydoc could be added manually or semi-manually.

What do you think?

Best regards,
Sven
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kdevelop-devel/attachments/20101117/19bb031e/attachment.html>