The Python docs are pretty good, though a few more examples sprinkled around would help, and the giant long pages covering a number of classes annoy me as if you google for something you then have to type a local browser find again on the page to find it.
As for calibre's API, Kovid used to build such help and include it in the online calibre manual. It doesn't seem to appear there any more - to be honest that is something I am happy about because I didn't believe an end user searching for a key word should be given search results showing low level coding API stuff. No problem with it being available online, just didn't think it belonged in the same search scope as the user manual. Though now (or at least here at work on IE8) there seems to be no search capability whatsoever in the calibre manual for anything - leaving it up to google I guess?
I think you are better off just loading the calibre source code up in the IDE you are developing your plugin in such as Eclipse, and using its search/navigation capabilities. I find it orders of magnitude more useful to see the actual underlying code in a class/function - particularly in case the documentation is out of date, missing or terse. With Eclipse/PyDev you get the preview in the tooltip and hyperlink navigation.
The biggest challenge I have with calibre's source code is that having a long history from multiple developers, there is a lot of legacy code hanging around and in many cases there are lots of namespaces and classes that are very similar to each other but for different purposes. Two years on and I still don't find the namespace hierarchy intuitive enough to be confident to be able to browse to a class file beyond the few I am forever referencing (like database2.py). Instead I tend to start from the calibre plugin code for a feature and work my way back through the code links to get to where the "real" code lives. That doesn't always work though due to the limitations of IDEs with Pythons dynamic and multi-inheritance nature with lack of interface contracts - once you hit something like self.gui.xxx or self.db.xxx then it becomes time to dig out the workspace search for xxx again to figure out where that code lives... it is a labour of love at times!
The stuff like the plugins API has excellent code documentation, plus you have dozens of examples in the forums to cater for "how would I do that?" along with the built in plugins in calibre's code. Beyond that it gets deep in the pool very quickly
