Merge pull request matplotlib#24715 from timhoffm/doc-axes-creation

Add note that users do not instantiate Axes directly

Author: ksunden

lib/matplotlib/axes/_axes.py

@@ -55,6 +55,12 @@ class Axes(_AxesBase):
     are 'xlim_changed' and 'ylim_changed' and the callback will be called with
     func(*ax*) where *ax* is the `Axes` instance.
 
+    .. note::
+
+        As a user, you do not instantiate Axes directly, but use Axes creation
+        methods instead; e.g. from `.pyplot` or `.Figure`:
+        `~.pyplot.subplots`, `~.pyplot.subplot_mosaic` or `.Figure.add_axes`.
+
     Attributes
     ----------
     dataLim : `.Bbox`

lib/mpl_toolkits/mplot3d/axes3d.py

@@ -45,6 +45,12 @@
 class Axes3D(Axes):
     """
     3D Axes object.
+
+    .. note::
+
+        As a user, you do not instantiate Axes directly, but use Axes creation
+        methods instead; e.g. from `.pyplot` or `.Figure`:
+        `~.pyplot.subplots`, `~.pyplot.subplot_mosaic` or `.Figure.add_axes`.
     """
     name = '3d'
 

tutorials/toolkits/mplot3d.py

@@ -24,10 +24,6 @@
    :target: ../../gallery/mplot3d/subplot3d.html
    :align: center
 
-.. versionchanged:: 1.0.0
-   Prior to Matplotlib 1.0.0, only a single `.Axes3D` could be created per
-   figure; it needed to be directly instantiated as ``ax = Axes3D(fig)``.
-
 .. versionchanged:: 3.2.0
    Prior to Matplotlib 3.2.0, it was necessary to explicitly import the
    :mod:`mpl_toolkits.mplot3d` module to make the '3d' projection to