From aaeda87306140204a065b15b6b85cb10e95ec5a9 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 23 May 2023 06:54:05 +0200
Subject: [PATCH] Add note that subfigure is still provisional to docstring

This matches the notes at

https://matplotlib.org/stable/gallery/subplots_axes_and_figures/subfigures.html#figure-subfigures
---
 galleries/examples/subplots_axes_and_figures/subfigures.py | 2 +-
 lib/matplotlib/figure.py                                   | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/galleries/examples/subplots_axes_and_figures/subfigures.py b/galleries/examples/subplots_axes_and_figures/subfigures.py
index 2b63384de2a3..9141ab61abef 100644
--- a/galleries/examples/subplots_axes_and_figures/subfigures.py
+++ b/galleries/examples/subplots_axes_and_figures/subfigures.py
@@ -14,7 +14,7 @@
 that subfigures can also have their own child subfigures.
 
 .. note::
-    ``subfigure`` is new in v3.4, and the API is still provisional.
+    The *subfigure* concept is new in v3.4, and the API is still provisional.
 
 """
 import matplotlib.pyplot as plt
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
index 39517e14d0e3..90aa3c77b518 100644
--- a/lib/matplotlib/figure.py
+++ b/lib/matplotlib/figure.py
@@ -1552,6 +1552,9 @@ def subfigures(self, nrows=1, ncols=1, squeeze=True,
         the same as a figure, but cannot print itself.
         See :doc:`/gallery/subplots_axes_and_figures/subfigures`.
 
+        .. note::
+            The *subfigure* concept is new in v3.4, and the API is still provisional.
+
         Parameters
         ----------
         nrows, ncols : int, default: 1
@@ -2151,6 +2154,9 @@ class SubFigure(FigureBase):
         axsR = sfigs[1].subplots(2, 1)
 
     See :doc:`/gallery/subplots_axes_and_figures/subfigures`
+
+    .. note::
+        The *subfigure* concept is new in v3.4, and the API is still provisional.
     """
 
     def __init__(self, parent, subplotspec, *,