Something like fig.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 of plt.subplot (if that guy accepts a gridspec too, I guess it does?), and of SubplotBase.__init__ (as that's where the logic resides).