Skip to content

[Doc]: Link API docs of pyplot wrappers to the corresponding Axes methods #23795

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
anntzer opened this issue Sep 1, 2022 · 3 comments
Closed

Comments

@anntzer
Copy link
Contributor

anntzer commented Sep 1, 2022

Documentation Link

No response

Problem

The API docs for the pyplot plotting functions are not connected to the corresponding Axes methods. This means that, for example, there is no easy way to reach the fill_between examples at https://matplotlib.org/devdocs/api/_as_gen/matplotlib.pyplot.fill_between.html (which may be e.g. where google sends you to), whereas they are present at https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.fill_between.html.

Suggested improvement

The easiest short-term solution may be to manually fix all backlink entries in examples to include both the Axes method and the pyplot wrapper, regardless of which one is actually showcased in the example.
OTOH it may be better to just merge the two API pages so e.g. Axes.fill_between and pyplot.fill_between are documented on the same page (as the contents are actually entirely identical) with both function names in the header (the function signature in bold). However this may require more fiddling with sphinx.

@tacaswell
Copy link
Member

I am in favor of linking, but against putting them on the same page. I would like the link to be in a sentance that reads something like "This pyplot function is a sate-full convenience wrapper about " 😈 .

@timhoffm
Copy link
Member

timhoffm commented Oct 15, 2022

Where would we want such a sentence?

  • At the top of the docs (personally 👎)
  • Before the Parameters section (i.e. at the end of the description block)
  • In a Notes section
  • As a see-also entry

@timhoffm
Copy link
Member

timhoffm commented Apr 4, 2024

Duplicate of #17786 and partially fixed by #27909 (for the auto-generated methods).

@timhoffm timhoffm closed this as completed Apr 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants