Documentation and other peoples' code seems to jump between the two. It's a really good example of the downsides of having too many ways to do the same thing in the same library.
https://github.com/rougier/matplotlib-tutorial
If you wan something deeper the same person has written a book:
Regarding the different APIs, this page [1] from the documentation attempts to compare them and provide code that generates the same result using the the different APIs.
[1] https://matplotlib.org/devdocs/users/explain/api_interfaces....
Pyplot is a global namespace procedural interface similar to matlab. If you find an example online using pyplot, it’s easy to find the axis. counterpart. For example, plt.title() becomes axis.set_title().
Axes and Figure reference API docs are very good.
No doubt, but half the time when I am looking online for how to do something off the beaten path, I find a documentation page or stackoverflow answer that (only) uses the other interface, and I have to flail about for a while to come up with the OOP equivalent.
[0] https://matplotlib.org/stable/tutorials/introductory/quick_s...
(The procedural / global state API is actually reasonable for interactive plotting from a REPL.)