DOC

jklymak · jklymak · commit 3c55453f6ae5 · 2020-04-14T08:20:18.000-07:00
diff --git a/doc/users/next_whats_new/2020-04-14-title-yparam.rst b/doc/users/next_whats_new/2020-04-14-title-yparam.rst
@@ -0,0 +1,8 @@
+`~.axes.Axes.set_title` gains a y keyword argument to control auto positioning
+------------------------------------------------------------------------------
+`~.axes.Axes.set_title` tries to auto-position the title to avoid any
+decorators on the top x-axis.  This is not always desirable so now
+*y* is an explicit keyword argument of `~.axes.Axes.set_title`.  It
+defaults to *None* which means to use auto-positioning.  If a value is
+supplied (i.e. the pre-3.0 default was ``y=1.0``) then auto-positioning is
+turned off.  This can also be set with the new rcParameter :rc:`axes.titley`.  
diff --git a/examples/text_labels_and_annotations/titles_demo.py b/examples/text_labels_and_annotations/titles_demo.py
@@ -1,9 +1,9 @@
 """
-===========
-Titles Demo
-===========
+=================
+Title positioning
+=================
 
-matplotlib can display plot titles centered, flush with the left side of
+Matplotlib can display plot titles centered, flush with the left side of
 a set of axes, and flush with the right side of a set of axes.
 
 """
@@ -16,3 +16,44 @@
 plt.title('Right Title', loc='right')
 
 plt.show()
+
+###########################################################################
+# The vertical position is automatically chosen to avoid decorators on the
+# topmost x-axis:
+
+fig, axs = plt.subplots(1, 2, constrained_layout=True)
+
+ax = axs[0]
+ax.plot(range(10))
+ax.xaxis.set_label_position('top')
+ax.set_xlabel('X-label')
+ax.set_title('Center Title')
+
+ax = axs[1]
+ax.plot(range(10))
+ax.xaxis.set_label_position('top')
+ax.xaxis.tick_top()
+ax.set_xlabel('X-label')
+ax.set_title('Center Title')
+plt.show()
+
+###########################################################################
+# Automatic positioning can be turned off by manually specifying the
+# *y* kwarg for the title or setting :rc:`axes.titley` in the rcParams.
+
+fig, axs = plt.subplots(1, 2, constrained_layout=True)
+
+ax = axs[0]
+ax.plot(range(10))
+ax.xaxis.set_label_position('top')
+ax.set_xlabel('X-label')
+ax.set_title('Manual y', y=1.0, pad=-14)
+
+plt.rcParams['axes.titley'] = 1.0    # y is in axes-relative co-ordinates.
+plt.rcParams['axes.titlepad'] = -14  # pad is in points...
+ax = axs[1]
+ax.plot(range(10))
+ax.set_xlabel('X-label')
+ax.set_title('rcParam y')
+
+plt.show()
