[pygtk] Documentation

Gustavo J. A. M. Carneiro gjc at inescporto.pt
Mon Sep 4 17:44:59 WST 2006


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

-- 
Gustavo J. A. M. Carneiro
<gjc at inescporto.pt> <gustavo at users.sourceforge.net>
The universe is always one step beyond logic.



More information about the pygtk mailing list