Adding index explanation to 'Controlling and Labelling Axis Objects" by mattymo30 · Pull Request #25805 · matplotlib/matplotlib

mattymo30 · 2023-05-02T03:15:50Z

PR summary

Following up on issue #25492, I added an indexed overview of the 'Controlling and Labelling Axis Objects' section of the user's explain page. The overview is a simple explanation of how Axis objects can be controlled and manipulated using the artist class. I also added reference links to the artist class and the examples of axis artist.

This is still a WIP, as I would like to add examples/written tutorials of this module.

PR checklist

"closes #0000" is in the body of the PR description to link the related issue
new and changed code is tested
[N/A ] Plotting related features are demonstrated in an example
[ N/A] New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

Wanted to implement a redirect to the examples' page for text, labels, and annotations, similar to the user_explain\colors\README.txt

Some capitalization issues, or capitalizing certain words (TrueType) that is typically capitalized

Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

Fixed reference to axis artist reference page Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

story645 · 2023-05-02T03:27:10Z

galleries/users_explain/axis/index.rst

+Matplotlib `~.axis.Axis` objects can be controlled and manipulated
+using the `~.artist.Artist` class. These tutorials cover the basics


My major concern is that this makes it sound like an Artist is a controller class of an Axis, when an Axis is a type of artist.
Maybe table set here for folks who aren't gonna read the doc? Like introduce what is an Axis in Matplotlib's notion of a figure/visualization, summarize/link out to what is an artist, and then make clear that an axis is a type of artist and what that means?

Ah okay. That does make more sense. I was still a little confused on the Axis API, so that really help. I'll try to reword it and work on it today or tomorrow (I am currently in my finals week for school so it may be a little delayed). Thank you!

After finals week is fine/this is definitely not more important and good luck!

I updated the description somewhat, and also added an inheritance diagram (from the Axis API page) to show how it is a type of Artist object. I also added a reference to that page. Let me know if what I wrote is any better and if I should change/add more to it. Thank you!

story645 · 2023-05-02T03:31:23Z

While my review is definitely critical, I'm super psyched you're taking the initiative to do this and so very much want to see these docs come into existence. Thanks so much!

Added inheritance diagram to show how it is inherited Added reference to axis_api page (also added a reference within that page so it can be linked)

jklymak · 2023-06-15T05:26:15Z

I think fixing this is definitely important. But the proposal here simply refers people to the Axis API, which isn't moving things forward a lot. @mattymo30 did you want to work on outlining something more comprehensive and have a go at it? I agree the API is confusing and maddeningly spread between Axis and Axes.

story645

I think it's kinda getting there, but the focus here should be a simple "what is an Axis"
I'd really like something to go in before #26110 because the text there feels very much like a placeholder, but I'm not sure if the timing works.

story645 · 2023-06-16T23:19:50Z

galleries/users_explain/axis/index.rst

+Almost every object interacted with on a Matplotlib plot is an "Artist,"
+which are a subclass of the `~matplotlib.artist.Artist` class. These objects
+help to customize and modify your Matplotlib figures and visualizations.


I think it's enough to say something like an Axis is an artist subclass, for more on manipulating artists see

Updated the description a little and just moved the link to the artists tutorial in this part

story645 · 2023-06-16T23:22:48Z

galleries/users_explain/axis/index.rst

+Matplotlib `~.axis.Axis` objects are a type of Artist that can help
+control and modify axes on a Matplotlib figure or visualization, which can
+include alignment, direction, style, curve, and more.


I think this is in the right direction, but is sort of lumping the Axis with the Axes in a way where it may not be clear which is which.

Changed it to axis to prevent confusion

story645 · 2023-06-18T05:16:43Z

Also @mattymo30 sorry that I dropped the ball on getting back to you. Please let us know if you'd like to finish this up.

mattymo30 · 2023-06-19T13:47:28Z

Also @mattymo30 sorry that I dropped the ball on getting back to you. Please let us know if you'd like to finish this up.

Sorry for the late reply, I've just been really busy lately. I'd be okay with finishing this up.

galleries/users_explain/axis/index.rst

story645 · 2023-06-26T22:24:26Z

galleries/users_explain/axis/index.rst

+Matplotlib `~.axis.Axis` objects are a type of Artist that can help
+control and modify axis on a Matplotlib figure or visualization, which can
+include alignment, direction, style, curve, and more.


It's more than that - the Axis artists are the underlying abstraction for an axis - basically the don't help control and modify, they are the code stand ins for the axis.

Also split the what it is and the what it controls into two sentences for some breathing room.

I tried to redefine the axis object to how you explained it to me. Let me know if it needs any more changing or updating

Maybe it's a meta problem that it's kinda a problem to use the word axes because it's too easy to confuse plotting axes with mpl Axes.

Co-authored-by: hannah <story645@gmail.com>

galleries/users_explain/axis/index.rst

story645 · 2023-06-30T21:00:03Z

galleries/users_explain/axis/index.rst

+Matplotlib `~.axis.Axis` objects are a type of Artist that
+are the underlying abstraction and the basis for the axes
+on a Matplotlib figure or visualization. Axis objects are


I think something got jumbled - an Axes contains two or more Axis. The Axis are kinda abstractions of the coordinate system. See anatomy of a plot: https://nbviewer.org/github/matplotlib/AnatomyOfMatplotlib/blob/master/AnatomyOfMatplotlib-Part1-Figures_Subplots_and_layouts.ipynb

I think I'm starting to get really confused on the concept of the axis artist now. I'm really struggling on how to describe it further

Yeah, sorry about that :/ It is confusing, especially cause of the axis/axes thing. I tried to write a short verison at #26205, but what do you think about the explanation in https://matplotlib.org/devdocs/users/explain/quick_start.html#axis-scales-and-ticks

I will re-iterate that I didn't write this section yet because it its very confusing, and indeed I'm strongly considering just dropping it and moving relevant material to Axes. I would not try and do this as a new contributor unless you have a vision for it.

I think I agree with Jody here and therefore I'm sorry Matty if I've made you feel like you're wasting your time. While I totally appreciate how much effort you've been putting in here, I'm thinking maybe your energy might be put to better use elsewhere. Even opening an issue on all the ways you've found this confusing would be helpful as guidance for someone writing the section.

Jody I think regardless of where this PR goes, this should be folded into the Axes section until it gets big and complicated enough to need its own.

Sorry for the very late reply (I've been extremely busy with another project), but no worries! It was definitely a challenge as a new contributor to try and write this documentation but I understand

Co-authored-by: hannah <story645@gmail.com>

story645

I think this is much improved! I'm very cool with merging this for now so there's content there and removing some of the urgency on getting the wider set of changes in #26279 in

jklymak

@story645 has argued elsewhere that this page should not exist. I agree. So I'm confused why we would add it. Certainly a release should not go out adding a page to just remove it a release later.

story645 · 2023-07-18T18:17:16Z

Certainly a release should not go out adding a page to just remove it a release later.

Because you marked the other PR release critical and I thought this placeholder could address the "critical b/c empty" issue while we sort through the larger questions around that section. I'd rather one page I'm iffy about go in than a whole bunch of content.

tacaswell · 2023-07-20T18:05:39Z

@mattymo30 I think this PR was made redundant by #26279 so I am going to close it. Thank you for your work on this even though we did not take it!

I hope we hear from you again.

mattymo30 and others added 11 commits April 3, 2023 22:12

Minor changes to user_explain\text\README.txt

c6d6d91

Wanted to implement a redirect to the examples' page for text, labels, and annotations, similar to the user_explain\colors\README.txt

Minor changes to user_explain\text\README.txt

7b95fb1

Wanted to implement a redirect to the examples' page for text, labels, and annotations, similar to the user_explain\colors\README.txt

Some minor typo/text changes in text/README.txt.

956c333

Some capitalization issues, or capitalizing certain words (TrueType) that is typically capitalized

Cookie cutter index overviewing the page and its tutorials.

37a7250

Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

Merge branch 'matplotlib:main' into main

a8f6b2c

Added reference link to tutorial on artist.

237a5db

Fixed reference to axis artist reference page Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

Added reference link to tutorial on artist.

9b4b6d1

Fixed reference to axis artist reference page Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

Added reference link to tutorial on artist.

65dcbc0

Fixed reference to axis artist reference page Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

Capitalization issues in title for axis\index.rst

89b50e1

Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

Capitalization issues in title for axis\index.rst

a075e66

Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

Removed initial stub in index.rst

8a68f87

Need to move/write examples that cover using and modifying axis objects (probably in axisartist module on the examples page)

story645 requested changes May 2, 2023

View reviewed changes

Updated description that Axis is a type of Artist

beb3e48

Added inheritance diagram to show how it is inherited Added reference to axis_api page (also added a reference within that page so it can be linked)

story645 approved these changes Jun 16, 2023

View reviewed changes

story645 requested changes Jun 16, 2023

View reviewed changes

Modifying artists and axis description

ad8d85b

mattymo30 requested a review from story645 June 20, 2023 13:34

story645 self-assigned this Jun 23, 2023

story645 reviewed Jun 26, 2023

View reviewed changes

mattymo30 and others added 3 commits June 30, 2023 13:16

Update galleries/users_explain/axis/index.rst

e2739d2

Co-authored-by: hannah <story645@gmail.com>

Redefining what the axis objects are

6f43412

Merge remote-tracking branch 'origin/main'

91a1531

story645 requested changes Jun 30, 2023

View reviewed changes

mattymo30 and others added 3 commits June 30, 2023 17:10

Update galleries/users_explain/axis/index.rst

dace3da

Co-authored-by: hannah <story645@gmail.com>

Update 'axex' to 'a single axis'

b99f0c0

Merge remote-tracking branch 'origin/main'

2bde170

melissawm added the Documentation label Jul 4, 2023

story645 approved these changes Jul 18, 2023

View reviewed changes

story645 added the Documentation: user guide files in galleries/users_explain or doc/users label Jul 18, 2023

jklymak reviewed Jul 18, 2023

View reviewed changes

tacaswell closed this Jul 20, 2023

		Matplotlib `~.axis.Axis` objects can be controlled and manipulated
		using the `~.artist.Artist` class. These tutorials cover the basics

Uh oh!

Conversation

mattymo30 commented May 2, 2023

PR summary

PR checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

story645 commented May 2, 2023

Uh oh!

jklymak commented Jun 15, 2023

Uh oh!

story645 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

story645 commented Jun 18, 2023

Uh oh!

mattymo30 commented Jun 19, 2023

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

story645 left a comment

Choose a reason for hiding this comment

Uh oh!

jklymak left a comment

Choose a reason for hiding this comment

Uh oh!

story645 commented Jul 18, 2023

Uh oh!

tacaswell commented Jul 20, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants