wxPython docs [was Re: Python Documentation Blows!]

[Robin Dunn]

Michael wrote:
> 
>> Is it time for the python community to commit a bit
>> more to the wxwidgets/wxpython environment?
>> I feel so
>>  
>>
> I lot of Python people don't like wxPython. I'm really not sure why as 
> it always works for me. 

Probably for the same reason I don't like tkinter.  It just doesn't fit 
my brain and wxWidgets does.  (This is the primary reason wxPython 
exists, because no matter how hard I tried I couldn't wrap my head 
around tkinter enough to write an app that I wanted to write.)  In most 
cases that I've seen if tkinter does fit well in somebody's brain then 
wxPython doesn't.  It's usually as simple as that.

Incidentally, I still havn't written that app!  I've been too busy and 
having too much fun with wxPython itself.


> I think wxPython is great but really needs more 
> of an experienced and vocal community and as I said some Python centric 
> documentation.
> 

It's coming.  In addition to the book and all that is involved in 
migrating to 2.5, (a lot of reachitecting, rewriting, etc. [1]), I'm 
working on Python-specific reference docs as well, starting with 
detailed docstrings.  I've patched SWIG to be able to automatically add 
a docstring that documents the parameters a function takes (eventhough 
it still uses (*args, **kwargs)) and the return type.  Then additional 
text can optionally be added to that and/or the auto-generated portion 
can be overriden for the cases that a typemap is involved and so custom 
details are needed.  This text will be usable from any tool that can can 
deal with docstrings, for example:

http://cvs.wxwidgets.org/viewcvs.cgi/wxWidgets/wxPython/docs/screenshots/PyShell.png?rev=1.1&content-type=text/vnd.viewcvs-markup

Additionally, all the metadata about the API (classes, methods, 
functions, parameters, types, docstrings, etc.) are being written to an 
XML file that will be included with the wxPython docs, and which should 
be able to be used by some tools (still to be written) to transform this 
into a browsable set of reference docs.


http://cvs.wxwidgets.org/viewcvs.cgi/wxWidgets/wxPython/docs/xml/wxPython-metadata.xml


[1] for info on some of the big changes in 2.5 see

http://cvs.wxwidgets.org/viewcvs.cgi/wxWidgets/wxPython/docs/MigrationGuide.txt

-- 
Robin Dunn
Software Craftsman
http://wxPython.org  Java give you jitters?  Relax with wxPython!