Python documentation

[Aleix Pol]

On Wed, Nov 17, 2010 at 4:46 PM, Sven Brauch <svenbrauch at googlemail.com>wrote:

> 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
>
> --
> KDevelop-devel mailing list
> KDevelop-devel at kdevelop.org
> https://barney.cs.uni-potsdam.de/mailman/listinfo/kdevelop-devel
>
>
Hi Sven!
I'm really happy to see anyone's interested on that! :) nice.

I think that it definitely makes sense to have the documentation in a SQLite
database, Qt does the same btw and it's not a big burden of a dependency,
I'd encourage you to use it.
Regarding the information recollection, I think it's fine to use pydoc
instead of actual python parsing (it's what we're doing with Qt also).

I'll be attentive to your progress.

Aleix
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kdevelop-devel/attachments/20101117/0eefd6e6/attachment.html>