Update diagram in subplots_adjust documentation to clarify parameters #30029
Conversation
There was a problem hiding this comment.
Thank you for opening your first PR into Matplotlib!
If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks.
You can also join us on gitter for real-time discussion.
For details on testing, writing docs, and our review process, please see the developer guide
We strive to be a welcoming and open project. Please follow our Code of Conduct.
|
This appears incorrect: |
|
Yes should be something like this |
| @@ -17,14 +18,14 @@ def arrow(p1, p2, **props): | |||
|
|
|||
| arrow((0, 0.75), (0.1, 0.75)) # left | |||
| arrow((0.435, 0.25), (0.565, 0.25)) # wspace | |||
| arrow((0.1, 0.8), (1, 0.8)) # right | |||
| arrow((0, 0.8), (0.9, 0.8)) # right | |||
There was a problem hiding this comment.
looking at the function and function calls, I think the arrow function adds in an unncessary layer of indirection given that the only argument actually passed in is the point. I think here it would be a lot clearer to just do:
arrowprops=dict(arrowstyle="<->", shrinkA=0, shrinkB=0)
xycoords = 'figure fraction'
overlay.annotate("", (0, 0.75), (0.1, 0.75)), xycoords=xycoords, arrowprops=arrowprops)
overlay.annotate("",(0.435, 0.25), (0.565, 0.25) , xycoords=xycoords, arrowprops=arrowprops)
overlay.annotate("", (0, 0.8), (0.9, 0.8), xycoords=xycoords, arrowprops=arrowprops)There was a problem hiding this comment.
Hi @story645 , thanks for the suggestion! I've updated the code to use the direct overlay.annotate() calls as you recommended :)
There was a problem hiding this comment.
@story645 I disagree. I intentionally introduced the arrow function as a semantic wrapper. I still find annotate("", xy1, xy2) a really awkward API. This is basically the discussion of #29826 (which is only deferred because we need to agree what the underlying artist should be), and the need for a reasonable high-level API still persists.
I'm not quite happy with reverting the wrapper, but since this is only an internal helper script and does not show up prominently in the docs, it's not worth fighting over.
There was a problem hiding this comment.
Sorry, but I also think doc examples are not the place to introduce new API. In this example, the extra arrow function to me felt very distracting once I figured out it wasn't doing anything extra. I would say here if anything then ConnectionPatch should just be used explicitly or the arrow function here should be wrapping ConnectionPatch.
There was a problem hiding this comment.
This is not intoducing new API and the code is not user-facing or teaching by intent. In my perspective, it's just a helper function making the example more readable for editors of that code. Obviously, YMMV. Let's not get into the discussion right now.
There was a problem hiding this comment.
Sorry, is kinda how I read `intentionally introduced the arrow function as a semantic wrapper. I still find annotate("", xy1, xy2) a really awkward API."
…entation to clarify parameters
…entation to clarify parameters
|
Thanks @Bindi003 and congratulations on your first contribution to Matplotlib 🎉! We'd be happy to see you again. |
…029-on-v3.10.3-doc Backport PR #30029 on branch v3.10.3-doc (Update diagram in subplots_adjust documentation to clarify parameters)
…029-on-v3.10.x Backport PR #30029 on branch v3.10.x (Update diagram in subplots_adjust documentation to clarify parameters)
PR summary
This pull request addresses an issue in the documentation for where the diagram incorrectly implied that the left, right, top, and bottom parameters were distances from the nearest subplot edges. In reality, these parameters represent distances from the edges of the figure (the overall plotting area).
Why is this change necessary?
The current diagram is misleading and contradicts the correct usage of subplots_adjust, potentially causing confusion for users trying to control subplot layout.
What is the reasoning for this implementation?
The implementation involves updating the Python script (doc/_embedded_plots/figure_subplots_adjust.py) that generates the diagram embedded in the documentation. The plotting code has been modified to accurately represent the relationship between the subplots_adjust parameters and the figure edges, matching the function's actual behavior.
PR checklist