Add documentation for align_titles

-

Add align_titles to api doc

Author: trananso

doc/api/figure_api.rst

@@ -71,6 +71,7 @@ Annotating
    Figure.align_labels
    Figure.align_xlabels
    Figure.align_ylabels
+   Figure.align_titles
    Figure.autofmt_xdate
 
 
@@ -264,6 +265,7 @@ Annotating
    SubFigure.align_labels
    SubFigure.align_xlabels
    SubFigure.align_ylabels
+   SubFigure.align_titles
 
 Adding and getting Artists
 --------------------------

doc/users/next_whats_new/figure_align_titles.rst

@@ -0,0 +1,7 @@
+subplot titles can now be automatically aligned
+-----------------------------------------------
+
+Subplot axes titles can be misaligned vertically if tick labels or
+xlabels are placed at the top of one subplot. The new method on the
+`.Figure` class: `.Figure.align_titles` will now align the titles
+vertically.

galleries/examples/subplots_axes_and_figures/align_labels_demo.py

@@ -1,37 +1,43 @@
 """
-===============
-Aligning Labels
-===============
+==========================
+Aligning Labels and Titles
+==========================
 
-Aligning xlabel and ylabel using `.Figure.align_xlabels` and
-`.Figure.align_ylabels`
+Aligning xlabel, ylabel, and title using `.Figure.align_xlabels`,
+`.Figure.align_ylabels`, and `.Figure.align_titles`.
 
-`.Figure.align_labels` wraps these two functions.
+`.Figure.align_labels` wraps the x and y label functions.
 
 Note that the xlabel "XLabel1 1" would normally be much closer to the
-x-axis, and "YLabel1 0" would be much closer to the y-axis of their
-respective axes.
+x-axis, "YLabel0 0" would be much closer to the y-axis, and title
+"Title0 0" would be much closer to the top of their respective axes.
 """
 import matplotlib.pyplot as plt
 import numpy as np
 
-import matplotlib.gridspec as gridspec
+fig, axs = plt.subplots(2, 2, layout='tight')
 
-fig = plt.figure(tight_layout=True)
-gs = gridspec.GridSpec(2, 2)
-
-ax = fig.add_subplot(gs[0, :])
+ax = axs[0][0]
 ax.plot(np.arange(0, 1e6, 1000))
-ax.set_ylabel('YLabel0')
-ax.set_xlabel('XLabel0')
+ax.set_title('Title0 0')
+ax.set_ylabel('YLabel0 0')
+
+ax = axs[0][1]
+ax.plot(np.arange(1., 0., -0.1) * 2000., np.arange(1., 0., -0.1))
+ax.set_title('Title0 1')
+ax.xaxis.tick_top()
+ax.tick_params(axis='x', rotation=55)
+
 
 for i in range(2):
-    ax = fig.add_subplot(gs[1, i])
+    ax = axs[1][i]
     ax.plot(np.arange(1., 0., -0.1) * 2000., np.arange(1., 0., -0.1))
     ax.set_ylabel('YLabel1 %d' % i)
     ax.set_xlabel('XLabel1 %d' % i)
     if i == 0:
         ax.tick_params(axis='x', rotation=55)
+
 fig.align_labels()  # same as fig.align_xlabels(); fig.align_ylabels()
+fig.align_titles()
 
 plt.show()

lib/matplotlib/figure.py

@@ -132,8 +132,7 @@ def __init__(self, **kwargs):
         self._supxlabel = None
         self._supylabel = None
 
-        # groupers to keep track of x, y labels and title we want to
-        # align.
+        # groupers to keep track of x, y labels and title we want to align.
         # see self.align_xlabels, self.align_ylabels,
         # self.align_titles, and axis._get_tick_boxes_siblings
         self._align_label_groups = {