Can I pick up this issue?

@gauravsawant absolutely! Thanks for your interest. The only gotcha is that some of the methods are created via boilerplate from their parents. Dealing with that may be harder than the hard-coded methods. Be sure to ping us if you have questions.

The boilerplate functions are conceptually easier. They just map to the Axes equivalent. It's just a matter of ammending the docstring in the boilerplate code. The other pyplot functions are the ones that need individual descriptions as they don't simply match 1:1. Some of them already have comments on this see e.g. the notes in https://matplotlib.org/devdocs/api/_as_gen/matplotlib.pyplot.xticks.html.

I think boilerplate and individual links should be done in two separate PRs as the required abilities are quite different.

On a general note, we should come up with a helpful message. IMHO a "See Also" without further comment is not very helpful. Something along the lines "This is the pyplot wrapper for Axes.text", where pyplot wrapper should be a link to an explanation of the pyplot vs. OO concepts - which I don't think we have a good summary of right now 😢. For the time being https://matplotlib.org/devdocs/api/index.html#usage-patterns may do.

Also to be considered: Should this be a "See also", or part of the "Notes" section or some dedicated (to be created) admonition. I would favor this to be consistent for all pyplot functions and some have already notes (e.g. https://matplotlib.org/devdocs/api/_as_gen/matplotlib.pyplot.xticks.html).

I almost think that See Also is enough. I don't know if we need a bunch of verbiage pointing out the two usage concepts for each docstring. But it is hard for folks who are used to plt.xlabel who then decide they need an axes handle, and then have to idea how to add an xlabel.

"See also" is de-facto used to link to similar and related functions. After reading the docstrings of the functions, one should be able to judge which function one should use for a given use-case. plt.xlabel and Axes.set_xlabel do exactly the same thing. The only difference is the usage idiom, and that should be mentioned somehow.

But it is hard for folks who are used to plt.xlabel who then decide they need an axes handle, and then have to idea how to add an xlabel.

In contrast, I imagine someone only used to pyplot reading the docs. If you are not familiar with the topic pyplot vs. OO usage pattern, a link without further explanation is confusing.

xref against #15922 cause I think an extra layer of confusion is that most of the examples in the pyplot section are actually OO.
But also all for this since I think it's part of what frustrated https://twitter.com/ecpensiveLife/status/1278804210793033729?s=19

Semi-OT, pyplot serves two purposes

1. the function based interface
2. "behind the scenes tasks" backend selection / figure management (+ creation with appropriate wiring) / event loop.

Number 2. is often still needed when using the OO interface, which makes it a bit confusing (also OO-style starts with pyplot.subplots or pyplot.figure). We're really not good at explaining this.

In the long run, I would like to see 2. moved out of pyplot (maybe dirctly into matplotlib); e.g. one could have mpl.subplots() and mpl.figure() as entry points so that the OO approach wound not import pyplot at all.

@gauravsawant Are you still working on this? Maybe we can work together on this if you're stuck

This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!

Good first issue - notes for new contributors

This issue is suited to new contributors because it does not require understanding of the Matplotlib internals. To get started, please see our contributing guide.

We do not assign issues. Check the Development section in the sidebar for linked pull requests (PRs). If there are none, feel free to start working on it. If there is an open PR, please collaborate on the work by reviewing it rather than duplicating it in a competing PR.

If something is unclear, please reach out on any of our communication channels.

Marking this as good first issue because it does not involve touching code that is user-facing, but medium difficulty because it will involve touching boilerplate.py which does code generation.

To work on this issue you should have a solid grasp of Python, be comfortable with stirng templating, be comfortable with the inspect module, and be willing to do some meta-programming.

I think we should only do the pyplot -> Axes method links but not the Axes method -> pyplot links.

Closed by #27909.