Something likefig.add_subplot(gridspec[0, 1]) isn't mentioned at all in the add_subplot docstring, it probably should be. Could additionally go to the docstrings ofplt.subplot (if that guy accepts a gridspec too, I guess it does?), and ofSubplotBase.__init__ (as that's where the logic resides).