DOC: Document tick objects

Closes matplotlib#31697

Author: timhoffm

doc/api/axes_api.rst

@@ -395,6 +395,8 @@ Aspect ratio
    Axes.set_adjustable
    Axes.get_adjustable
 
+.. _axes-api-ticks:
+
 Ticks and tick labels
 ---------------------
 

doc/api/axis_api.rst

@@ -80,6 +80,8 @@ Axis Label
    Axis.get_label_position
    Axis.get_label_text
 
+.. _axis-api-ticks:
+
 Ticks, tick labels and Offset text
 ----------------------------------
 

galleries/users_explain/axes/axes_ticks.py

@@ -227,6 +227,8 @@ def fmt_two_digits(x, pos):
 
 # %%
 #
+# .. _axes_ticks_styling:
+#
 # Styling ticks (tick parameters)
 # ===============================
 #
@@ -273,3 +275,53 @@ def fmt_two_digits(x, pos):
                        grid_color='none')
         ax.tick_params(axis='x', color='m', length=4, direction='in', width=4,
                        labelcolor='g', grid_color='b')
+
+# %%
+#
+# .. _axes-tick-objects:
+#
+# Tick objects
+# ============
+#
+# .. warning::
+#
+#     Ticks are managed through the autoscaling / view limit mechanism, which may
+#     create, move and delete ticks as necessary.
+#
+#     Working with tick instances should only be an option of last resort and requires
+#     careful handling to not accidentally overwrite any manual changes through this
+#     mechanism.
+#
+#     If a tick configuration can be achieved through `.Axes.tick_params` (see
+#     :ref:`axes-ticks-styling`), that approach should be preferred.
+#
+# On the technical level, ticks are realized through `.Tick` objects. They consist of
+#
+# - ``tick1line`` / ``tick2line`` for the tick lines on either side of the axis.
+# - ``label1`` / ``label2`` for the tick labels on either side of the axis.
+# - ``gridline`` for the grid line.
+#
+# These objects are publicly accessible through :ref:`Axes methods <axes-api-ticks>`
+# and :ref:`Axis methods <axis-api-ticks>` and allow extreme customization such as
+# coloring a specific tick line or tick label separately.
+
+x = 1.1 * np.exp(-3 * np.random.random(500))
+y = np.random.random(500)
+
+fig, ax = plt.subplots()
+
+ax.plot(x, y, 'o')
+ax.grid()
+ticks = ax.set_xticks([0, 0.2, 0.4, 0.6, 0.8, 1, 1.2])
+ticks[5].label1.set_color("red")
+ticks[5].tick1line.set_markeredgecolor("red")
+ticks[5].gridline.set(visible=True, linestyle=':', linewidth=1.5, color='red')
+
+# %%
+# Because of the managed nature of ticks, such operations only make sense for static
+# output (e.g., when using the jupyter inline backend or saving the figure to a file)
+# or when you are sure that the view limits of the axis will not change (e.g., when
+# using a fixed locator).
+#
+# In contrast, `.Axes.tick_params` configures the default properties so that they are
+# applied to all current and future ticks.

lib/matplotlib/axis.py

@@ -57,6 +57,15 @@ class Tick(martist.Artist):
     label2 : `~matplotlib.text.Text`
         The right/top tick label.
 
+    Notes
+    -----
+    Ticks are managed though the autoscaling / view limit mechanism and therefore
+    need very careful handling when explicitly accessed, see :ref:`axes-tick-objects`.
+
+    The tick lines are implemented as `~matplotlib.lines.Line2D` instances using the
+    `~.matplotlib.markers` TICKLEFT, TICKRIGHT, TICKDOWN, TICKUP. Therefore,
+    properties are controlled via the marker, e.g. for the color
+    `.Line2D.set_markeredgecolor` and not `.Line2D.set_color`.
     """
     def __init__(
         self, axes, loc, *,
@@ -84,9 +93,12 @@ def __init__(
         **kwargs,  # Other Line2D kwargs applied to gridlines.
     ):
         """
-        bbox is the Bound2D bounding box in display coords of the Axes
-        loc is the tick location in data coords
-        size is the tick size in points
+        Parameters
+        ----------
+        loc
+            The tick location in data coords.
+        size
+            The tick size in points.
         """
         super().__init__()