I think this is 💯 from a functionality point of view, but I am a bit worried about inventing a new link markup scheme and the re-writing to rst.

Can we just say "this is standard rst that will be rendered" and let the rst leak out to the in-line error message? If we think that is unacceptable, I would rather add another argument to the deprecation tools to allow what shows up in the documentation to be customized (rather than just dropping the value of alternative in). Text processing is hard in general and in my experience text-processing via regex can be very brittle, accepting a bit of duplication in code that is explicitly going to be deleted is probably less work overall than understanding some (admittedly clever) text mutation rules.

Maybe I should have better described the PR as "Allow rst in alternative for documentation and retrieve plain text from that rst for warnings".

inventing a new link markup scheme and the re-writing to rst

There is no new scheme or any re-writing to rst, everything is standard rst. The alternative is just added as is to the second argument of .. deprecated:: (which used to be just message), only the words Use and instead are prepended/appended for readability:

        second_arg = ' '.join([t.strip() for t in
                               (message, f"Use {alternative} instead."
                                if alternative else "", addendum) if t])

text-processing via regex can be very brittle

This is certainly true and I didn't mean to cover all possible corner cases when converting the rst into plain text for the warning. Complex rst expressions with nested and escaped `, < and > chars or malformed rst expressions will not be correctly handled by the regex, but what will happen: if it's a malformed rst expression, sphinx will issue a warning or an error when building the docs and the error should be fixed. If the rst is valid but too complex for the regex, some garbled text will be included in the warning message and, hopefully, someone will open an issue here (btw, I can't think of any case where such complex rst would be needed for an alternative, but it could happen of course; the three standard cases are covered by the test, I could add more exotic cases to the test). There won't be any runtime error or anything affecting the functionality of matplotlib.

Possible alternatives:

1. show the rst as-is in the warning

   • if its just a backticked link to another function it's not a big deal, rst where link and caption are different looks a bit strange

2. disallow usage of rst in alternative

   • documentation would be plain text only without links (and not to use rst can't be enforced anyway)
   • of course this is better than having no documentation of the alternative at all, but why not using the means provided by sphinx

3. add a new parameter alternative_rst to _api.deprecated etc.

   • quick and easy at the cost of writing the alternative two times
   • saves two lines of code: if alternative: alternative = re.sub(r"`([^`]*?) *<.*?>`|`\.?(.+?)`", r"\1\2", alternative)
   • API change

I just saw that the space between the caption and the link is optional (even not recommended although the examples in the rst spec contain spaces), so I changed the wording in the docs, the regex and the alternatives with separate captions accordingly. I also changed the test a bit to make it easier to read.

There is no new scheme or any re-writing to rst,

I misunderstood what was going on 🐑 . I thought that the transform was on the way into the rst not on the way into the warning text. I stand by my logic, but it is not relevant to this PR.

I do not think option 1 is terrible as even though it might look a bit funny, it does give more information about what is going on (by pointing to the class / method of interest). We have had some issues in the past where the alternative made perfect sense to us when we reviewed the PR (because we had the context of what class was being edited), it made no sense to users (because the class the method that was suggested as an alternative was on was not clear). It would be a shame to have that information in the source and documentation, but not visible at run time.

This is amazing! I'm very pro overall.

I'm also on the side of option 1 from #22038 (comment). I think the RST formatted text (at least in all the cases and types used in this PR) is parseable as plain text, and the removal of the RST markup isn't worth the hassle of maintaining a rather complex regular expression substitutuion.

I removed the rst text processing and pushed it as a separate commit (so it could be reverted easily in case someone complains about strange deprecation warning messages).

Thank you @StefRe !

OK, so this breaks the docs build if I have:

@_api.deprecated(
         "3.6", alternative="figure.get_layout_engine().set(**kwargs)")
    def set_constrained_layout_pads(self, **kwargs):

With WARNING: Inline strong start-string without end-string. Anything to be done here? Could just remove **kwargs...

You may try \*\*kwargs as a workaround.

But that looks terrible in the actual warning?

@jklymak I think enclosing it in backticks "`figure.get_layout_engine().set(**kwargs)`"should be enough to silence the warning . This will also neatly format the alternative as code in the docs. If you want to link to the set method of the layout engine as well, you could write "`figure.get_layout_engine().set(**kwargs)<Layout_engine.set>`" (given that get_layout_engine returns a Layout_engine object).

@meeseeksdev backport to 3.5.x

Something went wrong ... Please have a look at my logs.

It seems that the branch you are trying to backport to does not exist.

@meeseeksdev backport to v3.5.x