[WIP] Fix doc signature mismatch

Fixes #2062 

This is almost done, but I haven't cross checked with #2084 yet and a few more ( < 8 ) are yet to be done...

I'll refrain from force pushing over this commit to allow review comments to be visible... ( I'll squash those commits later on )

@jnothman @amueller @NelleV Kindly take a look... 
No the "``_covariance_type``" was formatted as a code snipped, which made the script unhappy... and more over we consistently name any attributes without any surrounding 
"``" so... :)