Improve documentation on Axes position #9951
Conversation
|
I think we've sort of converged on using double backquotes for True, False and None, which is probably as good as anything (technically single backquotes would also work, as they'd link to, well, the docs entry on docs.python.org for these objects; it's just a matter of consistency). |
2d797a4 to
b449346
Compare
|
I've now set True in backqoutes. @jklymak Thank you for the review. You write "suggested change below". Sorry, I don't know where "below" is. I haven't found the suggested change. Could you please hint, where I have to look? |
|
The github interface gets weird sometimes. Chances are, he typed out all
sorts of comments, but they didn't actually get submitted. It has happened
to me from time-to-time.
…On Sat, Dec 9, 2017 at 12:35 PM, Tim Hoffmann ***@***.***> wrote:
I've now set True in backqoutes.
@jklymak <https://github.com/jklymak> Thank you for the review. You write
"suggested change below". Sorry, I don't know where "below" is. I haven't
found the suggested change. Could you please hint, where I have to look?
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<#9951 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AARy-MY888JE9dxHKJKopfa0uA6jG0bjks5s-sT4gaJpZM4Q4z-V>
.
|
|
oh hmm guess I hit the wrong button somewhere. I’ll look again tonight. |
lib/matplotlib/axes/_base.py
Outdated
|
|
||
| The expected shape of ``pos`` is:: | ||
| There are two position variables: |
There was a problem hiding this comment.
This was the part I found a bit confusing, and I understand what you are talking about. Maybe:
Axes have two position attributes: the 'original' position is the position allocated for the axes; the 'active' position is the position the Axes is actually drawn at. These positions will usually be the same except if the Axes has its aspect ratio set by .apply_aspect.
lib/matplotlib/axes/_base.py
Outdated
| Reset the original position to the active position. This resets the | ||
| a possible position change due to aspect constraints. | ||
| For an explanation of the positions see `.set_position`. | ||
| """ |
There was a problem hiding this comment.
This is actually backwards (as was the original docstring!). Should be
Reset the 'active' position to the 'original' position, undoing the effect of ~.set_aspect.
There was a problem hiding this comment.
Changed to: "Reset the active position to the original position."
It's not really undoing the effect of set_aspect, but of apply_aspect, so I don't want to adapt the second half-sentence. But explaining this is a bit too much for the docstring.
As written in #9964:
Overall, I think we would need a dedicated help page outside the docstrings to explain, coordinates, scaling and the related terminology, which is not always consistent and/or self-explanatory.
There was a problem hiding this comment.
I think users will think of it as set_aspect. I also think that set_aspect is the sensible place to define all of this, so a link back to it would be helpful to users. apply_aspect could also be mentioned.
b449346 to
5c9b102
Compare
PR Summary
This PR improves the documentation of:
Also, it does some minor cleanups on a few other docstrings.
Style questions
Is there are basic description of the coordinate systems other/simpler than the Transforms tutorial?
TrueandFalsein the docstring text? Such as inIf *True*, return the original position.I've not found anything on this in the numpydocs or in https://github.com/matplotlib/matplotlib/blob/master/doc/devel/documenting_mpl.rst