8000 Better document Axes.transData and other transXYZ attributes by AnanasClassic · Pull Request #25922 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Better document Axes.transData and other transXYZ attributes #25922

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.

Sign up for GitHub

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

Jump to bottom
Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Better document Axes.transData and other transXYZ attributes #25922

wants to merge 8 commits into from

Conversation

AnanasClassic
Copy link
@AnanasClassic AnanasClassic commented May 19, 2023 •
edited
Loading

PR summary

Closes #25220
I added in _base.py defining the Axes.transData attribute and added documentation generation for it to axes_api.rst. It seems to me that this is enough for the user to understand from the github documentation what Axes.transData is.

PR checklist

@jklymak
Copy link
Member
jklymak commented May 19, 2023

Thanks for this. However, can you add a better title and move the cross reference to the description?

tacaswell
tacaswell reviewed May 19, 2023
View reviewed changes
@AnanasClassic AnanasClassic changed the title #25220 [Doc]: Better document Axes.transData May 19, 2023
@tacaswell
Copy link
Member

Per the discussion in #25220 there is some concern about doing this via this method and I agree with @ksunden if we are going to do this for one, we should do it for all.

tacaswell
tacaswell previously requested changes May 19, 2023
View reviewed changes
Copy link
Member
@tacaswell tacaswell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. I do not think that there is consensus on the best way to fix this per [Doc]: Better document Axes.transData and other transXYZ attributes #25220 (comment)
  2. If we are going to do this for one of the transXYZ we should to it for all of them in the same PR.

@AnanasClassic AnanasClassic changed the title [Doc]: Better document Axes.transData Better document Axes.transData and other transXYZ attributes May 19, 2023
@timhoffm
Copy link
Member

@tacaswell let's come to a decision

I read the linked comment by @ksunden as +0.5 for properties. I'm also +0.5 on properties (and would make them read-only) I can't read any preference from your comments.

@AnanasClassic
Copy link
Author

as I see it, we are going to properties. I think I implemented this in my last commit, and I'm ready to listen to what I should fix in my implementation. I also have a slightly naive question about failed tests: I don't quite understand how the changes I made caused errors in the tests (as far as I understand, the errors say about the conflict of Tkinter versions)

@AnanasClassic AnanasClassic requested a review from tacaswell May 22, 2023 15:19
@timhoffm
Copy link
Member

as I see it, we are going to properties.

I see it the same way, but @tacaswell doesn't seem so sure. Let's wait for his reply.

The test failures are unrelated. This is a configuration problem in the CI system for a specific version of OSX and tk.

@tacaswell
Copy link
Member

I added this to today's call agenda.

Moving to properties to get documentation seems backwards to me (we are imposing a run-time cost for a doc-build-time problem). These have not changed is years, could we explicitly list them in the class docstring instead?

@timhoffm
Copy link
Member

I‘m not sure I will make it to the call. Therefore, I add my 2cents right here:

Adding runtime cost just for doc would indeed sound odd, however

  • This makes the properties read-only, which they conceptually could/should be. (Not clear how protective we want to be here, but it is certainly justifiable).
  • The runtime cost is negligible in every practical usage scenario.

Overall I‘m +0.5 on properties. But it should alternatively be viable to list them in an Attributes section in the class docstring https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring.

@tacaswell
Copy link
Member

This makes the properties read-only,

The PR currently has setters for all 4.

@tacaswell
Copy link
Member

Consensus from call

  • go with properties
    • but do coarse bench marks to see if it matters
  • option to look at read-only
    • would need a deprecation cycle
    • check how disruptive this would be
  • consider renaming
  • the docstrings are not yet clear
    • need to be more explicit about source and target coordinate systems
    • link to transform tutorial

@tacaswell tacaswell dismissed their stale review May 25, 2023 20:16

outdated

@rcomer
Copy link
Member
rcomer commented Jul 15, 2023

Hi @AnanasClassic are you still interested in working on this one?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@tacaswell tacaswell Awaiting requested review from tacaswell

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
Documentation status: needs rebase status: needs revision status: orphaned PR topic: axes
Projects
First Time Contributors
Status: Waiting for author
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

[Doc]: Better document Axes.transData and other transXYZ attributes
7 participants
@AnanasClassic @jklymak @tacaswell @timhoffm @rcomer @QuLogic @melissawm
0