Why are you moving that docstring?

to hide it from https://matplotlib.org/api/contour_api.html#matplotlib.contour.QuadContourSet.contour_doc (it's now a regular docstring instead of being (from sphinx's PoV) a module-global variable).

Could the problem also be solved with a moderate change in contour_api.rst, specifying the things to be documented rather than using auto-everything?
The reason I ask is that keeping very long docstrings as separate strings improves code readability by putting the method signature close to its body. That was the original rationale in this case, and I think it still applies.

It is not clear to me what you mean in this specific case. I'm basically changing

class QuadContourSet:
    """long docstring"""
    <long contents of the class>

    contour_doc = """some long docs"""

to

class QuadContourSet:
    """long docstring"""

    def __init__(self, *args, **kwargs):
	    """some long docs"""

    <long contents of the class>

which seems, if anything (regardless of sphinx), better?

I don't agree that it is better; having a very long docstring between the signature and the code makes it a little harder to work with the code.

Could probably turn it into a private variable instead.

Switching to a private variable sounds like a good idea--it hadn't occurred to me!

edited accordingly

Thank you for the change in strategy with the contour docstring. What about the tricontour doc string? @ianthomas23 might want to have a look.

Side question: In the docstrings themselves, why are the "::" instances mostly separate paragraphs, wasting two full lines, instead of being at the ends of the preceding paragraphs? My understanding from the reSt documentation is that if they are at the end of a paragraph and separated by a space, this is equivalent to having them in their own paragraphs.

The '::' can definitely be moved into the previous paragraph (and I agree it'll make things more compact). But that should go into a separate PR (to keep the diff of this one clear as a "move-only").

I believe quite strongly that the tricontour docstring belongs directly under the tricontour() signature (for the case of contour() I moved it back out as there wasn't really a place to put it anyways and I had to "invent" a pass-through constructor to host it, which was not particularly elegant either).

To be honest I believe that your point about docstrings taking too much place is better solved by having your favorite code editor fold the docstring, e.g. the screenshots at the bottom of https://chrisdown.name/2015/02/26/folding-python-docstrings-in-vim.html (I use https://github.com/tmhedberg/SimpylFold).