[pygtk] Documentation

standa. standa_1 at centrum.cz
Mon Sep 11 06:36:14 WST 2006

Gustavo J. A. M. Carneiro wrote:
> On Dom, 2006-09-03 at 19:02 -0300, Johan Dahlin wrote:
>>> So I have some tips about documentation:
>>> 1. it would be great to have an option to enter my thoughts, tips, misunderstandings right on the documentation page. Like PHP does. I think it's good. IE i needed to create dialog box. It was simple. In last paragraph (dialog class) - ... you can call run()... Fine. Dialog appeared, but there is no info, what to do next. How to make it disappear. All what I was missing was - for closing the dialog call function destroy(). It took me 30min. I'd like to add this info to docs (or pass this info to maintainer of the docs), but how? Creating account in bugzilla and filling bug report is too "heavy" process to take just for sending this little info. Sending an email to some email account created for this purpose would be easier, but still not as simple as form directly on the docs page. And I think, there is plenty of "little informations" that could be collected from users.
>> Yes I agree totally. It's be very nice to have a comment system on top 
>> of the current
>> documentation.
>> It's a bit problematic though, because you need to be able to persist 
>> all the comments
>> somewhere and you also need to make sure that it's easy to update the 
>> original documentation against the one which is built from cvs.
>>> 2. While viewing info about classess there are viewed only methods and signals from the displayed class. But there are a lot of other methods form ancestors. It would be great to have all methods displayed in place. Like javadocs has. I think it's good. There could be problem, because som classess has a lot of methods and displaying all ancestors methods altogether can make a really long list. But there could be solutions how to accomplish it.
>> This would be very interesting as well, I'm not sure how it would be 
>> solved in practice.
>> Perhaps generating an alternative view, similar to javadoc would be an 
>> option for that.
>> Both of these are worthy goal, but unfortunately none of them are 
>> trivial to implement, they'd require someone with time and motivation to 
>> go ahead and solve them.
>   See:
> 	http://live.gnome.org/LiveDocumentationEditing
Sorry, but I'm not sure, what you are trying to tell me.
- I see there is a live.gnome.org. Sarma is used to make it happen/exist
- I found there is also live.gnome.org/pygtk

You want to say me - hey, it's already there - pygtk wiki, so if you
have problem / tips you can write it there.
What about using sarma for pygtk documentation and move existing docs to
sarma. Why create some stupid form when there is product who can make
much more?


More information about the pygtk mailing list