PR Summary

closes #12729

I messed my github matplotlib repo settings (and not github doesn't recognize my old branch... it says pharshalp wants to merge 1 commit into matplotlib:master from **unknown repository**) so closed the older PR and recreated it here.
Sorry for the noise!
Please see #16428 the reviewers' comments, suggestions and discussion.

MaxNLocator's docs were incorrect (please see the details described in #12729).

Here is a numerical experiment that I ran to determine the difference between the number of tick locations returned by MaxNLocator and the argument nbins.

import matplotlib.ticker as mticker
import numpy as np

steps = np.linspace(1, 10, 37)   # Overkill -- 1.  ,  1.25,  1.5 ,  1.75,  2.... , 10
vmax_arr = np.linspace(0, 1, 1001)[1:]  # Overkill

# number of ticks - number of bins
nticks_minus_nbins = np.zeros((1001, 40, 3), dtype=np.int64)
for vmax_ind, vmax in enumerate(vmax_arr):
    for nbins in range(1, 40+1):
        locator = mticker.MaxNLocator(nbins, steps=steps, min_n_ticks=1)
        nticks_minus_nbins[vmax_ind, nbins-1, 0] = len(locator.tick_values(0, vmax))-nbins
        nticks_minus_nbins[vmax_ind, nbins-1, 1] = len(locator.tick_values(-vmax, 0))-nbins
        nticks_minus_nbins[vmax_ind, nbins-1, 2] = len(locator.tick_values(-vmax, vmax))-nbins
print(np.max(nticks_minus_nbins))  # returns 2

It turns out (as was shown in the original issue) that MaxNLocator returns at most nbins+2 tick locations (nbins+1 intervals).

Since contour/contourf uses MaxNLocator (as pointed out in the original issue) updated their docs as well.

PR Checklist

• Has Pytest style unit tests
• Code is Flake 8 compliant
• New features are documented, with examples if plot related
• Documentation is sphinx and numpydoc compliant
• Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
• Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way