Skip to content
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

Canonicalization for 're'-inherited methods #60

Open
QuLogic opened this issue Mar 27, 2021 · 4 comments
Open

Canonicalization for 're'-inherited methods #60

QuLogic opened this issue Mar 27, 2021 · 4 comments

Comments

@QuLogic
Copy link
Member

QuLogic commented Mar 27, 2021

In 3.4.0, the docs for some Axes methods (pick, pickable, get_picker, set_picker, get_contains, set_contains) were removed. This is because the docs are inherited from the Artist methods.

Sphinx automatically switches all references when generated the docs, but our redirect/canonicalization script here doesn't recognize it. Instead, it thinks these methods were last documented in 3.3.4 and points there.

We should decide if we want to point to the new location (and figure out if it's possible), and do so.

@QuLogic
Copy link
Member Author

QuLogic commented Mar 27, 2021

A siimilar case is in doc/api/figure_api.rst, where the individual members were listed in _as_gen, but the subfigure change (matplotlib/matplotlib@608a6e6#diff-0b83637c05ce3106a94726a356f22c1cb198257c7e7bd5f66be70cd4a20ebe5b) moved them to automodule-only, and they are now documented in the file instead of separate files in _as_gen.

@jklymak
Copy link
Member

jklymak commented Mar 27, 2021

I'm a little confused as to what the problem is. https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.pick.html#matplotlib.axes.Axes.pick is gone. I guess
https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.pick.html#matplotlib.axes.Axes.pick should just map to 3.3.4. Its not like you will be able to reach it from our docs, its just to satisfy bad links. Or are there further problems?

@QuLogic
Copy link
Member Author

QuLogic commented Mar 27, 2021

Well, in this case, it's gone because it's in https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.pick.html
The method still exists as Axes.pick, but the location of where it's documented has moved.

@jklymak
Copy link
Member

jklymak commented Mar 27, 2021

Sure, but we can't catch all that.... To me the goal is to not completely kill a top-level link. https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.pick.html should never be linked, but if someone does link it, we are sending them to where the documentation last existed. That we removed it and are relying on the inherited method isn't something we can help with. Note the reference in the list of axes methods has gone as well.

(Off topic, but I don't think this was a particularly good idea from a documentation point of view. Sure not every artist should have pick documented, but axes is kind of a special case, and removing it from the API index strikes me as making things more confusing, not less so).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants