Update find_nearest_contour and revert contour deprecations

[rcomer]

PR summary

• Following [Bug]: find_nearest_contour deprecated with no replacement? #27070 (comment), this PR updates the ContourSet.find_nearest_contour method so it no longer uses the deprecated collections attribute.

  Note that the docstring previously stated in error that the first element of the returned tuple is a Collection. It was actually an integer that indexed the collections attribute. Since <3.8 behaviour had one collection per level, and in 3.8 we have one path per level I have updated this to say the index of the path.

• contour.allsegs, contour.allkinds, and contour.find_nearest_contour are no longer marked for deprecation.

Closes #27070 and closes #26913

PR checklist

• "closes #0000" is in the body of the PR description to link the related issue
• new and changed code is tested (existing tests cover this)
• [n/a] Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• [n/a] Documentation complies with general and docstring guidelines

[rcomer]

I'm using "segment" here to mean one of the pieces you get when you split the path by its MOVETOs. I'm not sure I have the language right though. What exactly defines a segment?

[anntzer]

connected component, I think

[QuLogic]

The word 'segment' is a bit confusing, because Paths have a method iter_segments, which splits by code, i.e., a MOVETO returns one point, a CURVE3 returns two points, etc. This does not appear to be the same as the 'segment' used here.

[rcomer]

So should I change “segment” to “connected component” here? Or something else?

[QuLogic]

I guess it could be a 'subpath'?

[rcomer]

"subpath" is what I have called the variable when I've looped through these, so that is intuitive to me 👍

[rcomer]

OK I have changed it to "subpath" and also added some explanation of what paths and subpaths correspond to in the plot.

[rcomer]

Updated based on #27070 (comment). There is a possibility for all the return values to be None, but I think this can only happen if the paths are all empty, which seems artificial. There is also no test for that case.

[anntzer]

I have a slight preference for using the _cm_set approach for handling the pixel=False (if that indeed works, untested) so that the backcompat code doesn't start interfering with the "main intended usage" code.

[rcomer]

It does work. It just seemed odd to me to essentially hack the method's behaviour from outside when directly changing the behaviour was very simple. I will defer to you on that though.