All pygtk ebuilds from pygtk-2.4.1.ebuild onwards provide documentation using the archive file pygtk2reference.tbz2. The version of pygtk2reference.tbz2 currently in distfiles is 2.5.1 (covering PyGTK 2.5.1). i.e. whichever version of pygtk you emerge you get the 2.5.1 docs. Not sure there is a neat fix for this, only to ask the project to put version numbers in the filename (or at least links on their website).
We'll hope upstream likes the idea :) http://bugs.gnome.org/show_bug.cgi?id=318906
re-opening
*** Bug 111860 has been marked as a duplicate of this bug. ***
*** Bug 140311 has been marked as a duplicate of this bug. ***
upstream did just break out the tarballs, so the next revision we will use the versioned ones.
Created attachment 101761 [details, diff] pygtk-2.10.3-refdoc.patch Finally found where these versioned docs are (thanks to Google). Patch to 2.10.3 (borrowing from gnome.org.eclass)
Created attachment 102413 [details, diff] pygtk-2.10.3-includes-doc.patch Scrub #6. Reference manual is now in the tar ball as of 2.10.0, so were being installed in /usr/share/gtk-doc/html/pygtk anyway (thanks to gnome.org.eclass). So here's a patch to remove the separate download of pygtk2reference.tbz2 from pygtk-2.10.3.
Created attachment 105152 [details, diff] pygtk-2.10.3-images-from-ref.patch Turns out the docs in pygtk tarball don't include images. So this version uses pygtk2reference.tbz2 just for the images. There is an unnoticed pygtk bug on this: http://bugzilla.gnome.org/show_bug.cgi?id=375115
Created attachment 105154 [details, diff] pygtk-2.10.3-images-from-newref.patch There are more icons in the newer reference tarball...
Fixed. Thanks for the diff.