[PyKDE] Feedback Requested on PyQt4 Documentation

[Phil Thompson]

The only work I plan to do before the final release of PyQt4 is to improve the 
documentation.

I've just updated http://www.riverbankcomputing.com/Docs/PyQt4/pyqt4ref.html 
and would like some comments before I wander off up a blind alley.

First thing - don't get too excited - what I've done so far obviously isn't 
usable. I just wanted to get something up to start a discussion.

For me, the documentation...

- must describe the complete API as implemented by PyQt in Pythonic terms

- must be automatically generated (almost) completely

- must be easy to navigate

- is not intended to replace the Qt documentation.

The documentation has been generated by adding an XML export flag to SIP and 
writing a simple Python script that generates reStructuredText from the XML. 
The standard reST tools are used to generate HTML.

I chose reST because it's easy to generate decent looking HTML from 
handwritten text. I'm not entirely convinced it is powerful enough for the 
API part of the documentation. It's easy enough to change my Python script to 
generate some other markup.

The most obvious problems with what I've done so far is the huge table of 
contents and the lack of separation between the different elements of the API 
making it very difficult to find things.

Perhaps just modeling it on the Qt documentation is the easiest thing to do.

I'd also point out that I have no talent whatsoever for graphic design.

Anyway, I'd welcome any comments and suggestions.

Phil