[PyQt] Howto use the Qt documentation successfully

[Hans-Peter Jansen]

On Wednesday 15 September 2010, 19:50:11 Robert Lummis wrote:
> I'd like to second Peter Milliken's sentiments. The PyQt documentation
> that's available is (in my opinion) pretty poor. Finding a way to do
> something that you haven't done before by browsing the documentation
> is nearly impossible. Or at least it's so frustrating and
> time-consuming that I often give up before finding what I need. The
> only way I've successfully implemented something is by starting with a
> working example I find by googling or in Mark Summerfield's book and
> vary it to suit my needs. That's not an ok method for serious
> programming.
>
> To be more concrete, I think there are at least two main shortcomings.
> 1)  good meta-documentation isn't available. (Or, if it is available,
> I haven't found it.) One part of the meta-documentation would guide
> you to the classes, procedures, etc. you should read based on the
> tasks you want to accomplish, and say which classes "go together".  It
> would contain indexed annotations on the existing pages so, for
> example, if I want to program a way to edit fields in a database I
> could look in its index under "fields" or "database" or "edit" and I
> would be taken to a listing of all the relevant classes (not just the
> ones with those words on their pages) with annotations about what each
> does. Or if I want to control an external device I would find an
> annotated listing of the classes that might be applicable.  This would
> have to be written by hand, not generated by a program.

While I understand your needs, I never came across a project, that provided 
a considerable amount of such meta documentation. All GUI programming 
books/manuals do this by example. Assistant comes close, since it has 
groupings of classes (e.g. "Database classes"), and topic overviews 
(e.g. "The Qt 4 Database GUI Layer").

> 2) The 
> existing documentation itself, while extensive and obviously the
> result of a huge effort, is still not good enough. For one thing it
> assumes knowledge of C++. That is lame because a key advantage of PyQt
> is that you can be productive without knowing C++.

I beg to disagree: what you need to learn is what parts of C++ism's you can 
ignore completely, and what parts need be be transformed.

Maybe, we should put a mini C++ survival guide into the PyQt wiki, that 
explains the basics..

> Also, many of the 
> pages have missing information, such as the list of arguments for a
> class, and/or have missing or broken links, or the explanations refer
> to arguments by name and the names don't match the names in the class
> heading. All of these taken together, along with other shortcomings
> I'm not mentioning, add up to a major barrier to learning. I guess if
> you already know a lot of PyQt the documentation seems good because it
> lets you look up some detail you didn't memorize. But it isn't very
> helpful to potential users who don't know a lot yet.

I'm so used to assistant, that I only occasionly lookup things in the PyQt 
documentation (apart from pyqt4ref.html of course). If I find a deviation  
from Qt in PyQt, I go straight into the sip files, since they contain both: 
a description of that, and the method signatures, I'm usually after.

> I hope nobody takes these comments as personal criticisms because they
> aren't meant as such. I am in awe at the talents, dedication, and hard
> work by the Qt and PyQt developers and the gurus on this list who are
> putting so much time into supporting PyQt users and learners. I'm
> trying to be constructive by giving feedback from a typical learner,
> and possibly spark a new effort to improve the documentation. I want
> to learn to use PyQt and I'm willing to put a lot of time into it, but
> the state of the documentation makes it unnecessarily hard. I haven't
> given up yet but I'm pretty discouraged.
>
> If I'm wrong about what is lacking, which I may be, I hope someone
> will (tactfully) enlighten me. However, even if I'm wrong my
> frustration is an indication that everything isn't what it should be.

Please try to find your way through assistant, and call back with the issues 
you have. I'm sure, that you won't miss much after a while.

C++ is bitchy, if you need to program with it, but happily, we can ignore 
all those ugly and black voodoo parts completely. 

With the raise of Python 3 and the declination of QString and QVariant, 
programming with PyQt has a even brighter future to offer.

Pete