fig.gca() vs. fig.add_subplot()

plt.gca gets the current axes, creating one if needed. It is only equivalent in the simplest 1 axes case.

The preferred way is to use plt.subplots (and the docs/examples are indeed lagging a bit, if you want to start contributing, updating the docs is a great place to start):

fig, ax = plt.subplots(1, 1)

or

fig, (ax1, ax2) = plt.subplots(2, 1)

and so on.

To creat 3D instance, there are three ways:

plt.gca(projection='3d')

plt.subplot(projection='3d')

fig = plt.figure()
fig.add_subplot(111, projection='3d') 

Maybe the third way is more complex.