Add documentation for _api module

timhoffm · timhoffm · commit 644872bceae1 · 2020-10-19T11:01:54.000+02:00
diff --git a/doc/api/_api_api.rst b/doc/api/_api_api.rst
@@ -0,0 +1,13 @@
+*******************
+``matplotlib._api``
+*******************
+
+.. automodule:: matplotlib._api
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: matplotlib._api.deprecation
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/cbook_api.rst b/doc/api/cbook_api.rst
@@ -6,8 +6,3 @@
    :members:
    :undoc-members:
    :show-inheritance:
-
-.. automodule:: matplotlib.cbook.deprecation
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -126,6 +126,7 @@ Matplotlib consists of the following submodules:
    type1font.rst
    units_api.rst
    widgets_api.rst
+   _api_api.rst
 
 Toolkits
 --------
diff --git a/doc/api/prev_api_changes/api_changes_3.0.0.rst b/doc/api/prev_api_changes/api_changes_3.0.0.rst
@@ -405,7 +405,7 @@ The following classes, methods, functions, and attributes are deprecated:
 - ``textpath.TextToPath.tex_font_map``
 - ``matplotlib.cbook.deprecation.mplDeprecation`` will be removed
   in future versions. It is just an alias for
-  :class:`matplotlib.cbook.deprecation.MatplotlibDeprecationWarning`.  Please
+  ``matplotlib.cbook.deprecation.MatplotlibDeprecationWarning``.  Please
   use ``matplotlib.cbook.MatplotlibDeprecationWarning`` directly if necessary.
 - The ``matplotlib.cbook.Bunch`` class has been deprecated. Instead, use
   `types.SimpleNamespace` from the standard library which provides the same
diff --git a/doc/api/prev_api_changes/api_changes_3.1.0.rst b/doc/api/prev_api_changes/api_changes_3.1.0.rst
@@ -767,12 +767,12 @@ The following signature related behaviours are deprecated:
   keyword.
 - The *interp_at_native* parameter to `.BboxImage`, which has had no effect
   since Matplotlib 2.0, is deprecated.
-- All arguments to the `~.cbook.deprecation.deprecated` decorator and
-  `~.cbook.deprecation.warn_deprecated` function, except the first one (the
-  version where the deprecation occurred), are now keyword-only.  The goal is
-  to avoid accidentally setting the "message" argument when the "name" (or
-  "alternative") argument was intended, as this has repeatedly occurred in the
-  past.
+- All arguments to the ``matplotlib.cbook.deprecation.deprecated`` decorator
+  and ``matplotlib.cbook.deprecation.warn_deprecated`` function, except the
+  first one (the version where the deprecation occurred), are now keyword-only.
+  The goal is to avoid accidentally setting the "message" argument when the
+  "name" (or "alternative") argument was intended, as this has repeatedly
+  occurred in the past.
 - The arguments of `matplotlib.testing.compare.calculate_rms` have been renamed
   from ``expectedImage, actualImage``, to ``expected_image, actual_image``.
 - Passing positional arguments to `.Axis.set_ticklabels` beyond *ticklabels*
@@ -1076,8 +1076,8 @@ Undeprecations
 --------------
 The following API elements have been un-deprecated:
 
-- The *obj_type* keyword argument to the `~.cbook.deprecation.deprecated`
-  decorator.
+- The *obj_type* keyword argument to the
+  ``matplotlib.cbook.deprecation.deprecated`` decorator.
 - *xmin*, *xmax* keyword arguments to `.Axes.set_xlim` and *ymin*, *ymax*
   keyword arguments to `.Axes.set_ylim`
 
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -511,7 +511,7 @@ There are five levels at which you can emit messages.
 
 - `logging.critical` and `logging.error` are really only there for errors that
   will end the use of the library but not kill the interpreter.
-- `logging.warning` and `.cbook._warn_external` are used to warn the user,
+- `logging.warning` and `._api.warn_external` are used to warn the user,
   see below.
 - `logging.info` is for information that the user may want to know if the
   program behaves oddly. They are not displayed by default. For instance, if
@@ -527,16 +527,16 @@ By default, `logging` displays all log messages at levels higher than
 ``logging.WARNING`` to `sys.stderr`.
 
 The `logging tutorial`_ suggests that the difference between `logging.warning`
-and `.cbook._warn_external` (which uses `warnings.warn`) is that
-`.cbook._warn_external` should be used for things the user must change to stop
+and `._api.warn_external` (which uses `warnings.warn`) is that
+`._api.warn_external` should be used for things the user must change to stop
 the warning (typically in the source), whereas `logging.warning` can be more
-persistent. Moreover, note that `.cbook._warn_external` will by default only
+persistent. Moreover, note that `._api.warn_external` will by default only
 emit a given warning *once* for each line of user code, whereas
 `logging.warning` will display the message every time it is called.
 
 By default, `warnings.warn` displays the line of code that has the ``warn``
 call. This usually isn't more informative than the warning message itself.
-Therefore, Matplotlib uses `.cbook._warn_external` which uses `warnings.warn`,
+Therefore, Matplotlib uses `._api.warn_external` which uses `warnings.warn`,
 but goes up the stack and displays the first line of code outside of
 Matplotlib. For example, for the module::
 
@@ -559,13 +559,13 @@ will display::
     UserWarning: Attempting to set identical bottom==top
     warnings.warn('Attempting to set identical bottom==top')
 
-Modifying the module to use `.cbook._warn_external`::
+Modifying the module to use `._api.warn_external`::
 
-    from matplotlib import cbook
+    from matplotlib import _api
 
     def set_range(bottom, top):
         if bottom == top:
-            cbook._warn_external('Attempting to set identical bottom==top')
+            _api.warn_external('Attempting to set identical bottom==top')
 
 and running the same script will display::
 
diff --git a/lib/matplotlib/_api/__init__.py b/lib/matplotlib/_api/__init__.py
@@ -1,3 +1,12 @@
+"""
+Helper functions for managing the Matplotlib API.
+
+.. warning:
+
+    This module and its submodules is for internal use only.
+
+"""
+
 import itertools
 import re
 import sys
