DOC: Remove Tick object details from artist tutorial#31692
Conversation
Closes matplotlib#31682. Don't explain the object structure and accessor methods to Tick objects and their constituent artists. Users should rarely use them as they are dynamically created and modified. - Remove the complete section on "Tick containers". Users really should access the individual parts through a Tick instance. The technical API still remains accessible in https://matplotlib.org/stable/api/axis_api.html#matplotlib.axis.Tick - Remove all the tick parts getter functions and instead point users to formatters, locators and tick_params.
| # Tick containers | ||
| # --------------- | ||
| # | ||
| # The :class:`matplotlib.axis.Tick` is the final container object in our | ||
| # descent from the :class:`~matplotlib.figure.Figure` to the | ||
| # :class:`~matplotlib.axes.Axes` to the :class:`~matplotlib.axis.Axis` | ||
| # to the :class:`~matplotlib.axis.Tick`. The ``Tick`` contains the tick | ||
| # and grid line instances, as well as the label instances for the upper | ||
| # and lower ticks. Each of these is accessible directly as an attribute | ||
| # of the ``Tick``. | ||
| # | ||
| # ============== ========================================================== | ||
| # Tick attribute Description | ||
| # ============== ========================================================== | ||
| # tick1line A `.Line2D` instance | ||
| # tick2line A `.Line2D` instance | ||
| # gridline A `.Line2D` instance | ||
| # label1 A `.Text` instance | ||
| # label2 A `.Text` instance | ||
| # ============== ========================================================== |
There was a problem hiding this comment.
I am not sure how I feel about removing this section. Although I of course agree that we don't want to encourage users to directly modify the ticks, the section could be of interest to someone who just wants to know how it all fits together. There is a thread running through the whole tutorial that everything you see in the plot is ultimately made from the primitive artists, and this maybe helps to complete that.
There was a problem hiding this comment.
This section consists of three parts:
- The statement that it's the final "container" in the hierachry. - IMHO not too meaningful by itself.
- The list of constituent Artists. - This is still available in the Tick API
- An example that fit the context anymore. Some time ago we have largely replaced usage of the explicit objects by
tick_params- including at this side, where we didn't realize this defeats the purpose. While one could revert this, I think this is an indicator that the section should not exists.
I'm inclined to say that these are implementation details a user should not need to know. - At least I wish we were in that state and I would want to move in that direction. The whole ticks concept should be handled through a single object, something like a tick collection (likely not a collection in the sense of our Collection class), but some aggregate object as the single public interface. This may internally be implemented via Line2Ds and Texts, or maybe we want a LineCollection, or something else completely.
You could argue that we're not yet there and therefore should explain the constituents. I was hoping that we can just be silent about it because it's aspirationally not relevant. The issue is that the section as is without giving scope and guidance is the worst option. Removing it is better than keeping. I could alternatively restore and add a big warning "for information only, don't use" at the top of the section. I don't have the willingess or time to rewrite the section into something reasonably right, helpful and understandable, in particular given that the overall tutorial has several and more severe shortcomings.
Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>
Closes #31682.
Don't explain the object structure and accessor methods to Tick objects and their constituent artists. Users should rarely use them as they are dynamically created and modified.