DOC: Fix references in cbook.

QuLogic · QuLogic · commit 3fc8fbbcb21c · 2020-09-03T17:01:26.000-04:00
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,11 +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.deprecated` decorator and `.cbook.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 `~.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.
 - 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*
@@ -1073,11 +1074,12 @@ This only served as a helper to the private `.Axis._update_ticks`
 
 Undeprecations
 --------------
-The following API elements have bee un-deprecated:
+The following API elements have been un-deprecated:
 
-- The *obj_type* kwarg to the `.cbook.deprecated` decorator.
-- *xmin*, *xmax* kwargs to `.Axes.set_xlim` and *ymin*, *ymax* kwargs
-  to `.Axes.set_ylim`
+- The *obj_type* keyword argument to the `~.cbook.deprecation.deprecated`
+  decorator.
+- *xmin*, *xmax* keyword arguments to `.Axes.set_xlim` and *ymin*, *ymax*
+  keyword arguments to `.Axes.set_ylim`
 
 
 New features
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -514,7 +514,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 `.cbook._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
@@ -529,18 +529,17 @@ There are five levels at which you can emit messages.
 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 the warning (typically in the source), whereas
-`logging.warning` can be more persistent.  Moreover, note that
-`cbook._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.
+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
+the warning (typically in the source), whereas `logging.warning` can be more
+persistent. Moreover, note that `.cbook._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`, but goes
+Matplotlib uses `.cbook._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::
 
@@ -563,7 +562,7 @@ 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 `.cbook._warn_external`::
 
     from matplotlib import cbook
 
diff --git a/doc/missing-references.json b/doc/missing-references.json
@@ -808,19 +808,6 @@
     "can_composite": [
       "lib/matplotlib/image.py:docstring of matplotlib.image.composite_images:9"
     ],
-    "cbook._warn_external": [
-      "doc/devel/contributing.rst:493",
-      "doc/devel/contributing.rst:508",
-      "doc/devel/contributing.rst:517",
-      "doc/devel/contributing.rst:542"
-    ],
-    "cbook.deprecated": [
-      "doc/api/prev_api_changes/api_changes_3.1.0.rst:1074",
-      "doc/api/prev_api_changes/api_changes_3.1.0.rst:766"
-    ],
-    "cbook.warn_deprecated": [
-      "doc/api/prev_api_changes/api_changes_3.1.0.rst:766"
-    ],
     "cleanup": [
       "lib/matplotlib/animation.py:docstring of matplotlib.animation.HTMLWriter.setup:19"
     ],
@@ -915,13 +902,6 @@
       "doc/devel/contributing.rst:468",
       "doc/devel/contributing.rst:505"
     ],
-    "ls_mapper": [
-      "doc/api/prev_api_changes/api_changes_1.5.0.rst:11"
-    ],
-    "ls_mapper_r": [
-      "doc/api/prev_api_changes/api_changes_1.5.0.rst:11",
-      "doc/api/prev_api_changes/api_changes_1.5.0.rst:8"
-    ],
     "mainloop": [
       "lib/matplotlib/backends/backend_nbagg.py:docstring of matplotlib.backends.backend_nbagg.show:4"
     ],
@@ -1281,10 +1261,6 @@
     "matplotlib.animation.TimedAnimation.to_jshtml": [
       "doc/api/_as_gen/matplotlib.animation.TimedAnimation.rst:23:<autosummary>:1"
     ],
-    "matplotlib.cbook.ls_mapper": [
-      "doc/api/prev_api_changes/api_changes_1.5.0.rst:11",
-      "doc/api/prev_api_changes/api_changes_1.5.0.rst:8"
-    ],
     "matplotlib.colorbar.ColorbarBase.set_clim": [
       "doc/api/prev_api_changes/api_changes_3.1.0.rst:290"
     ],
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -483,7 +483,7 @@ def get_sample_data(fname, asfileobj=True, *, np_load=False):
 
 def _get_data_path(*args):
     """
-    Return the `Path` to a resource file provided by Matplotlib.
+    Return the `pathlib.Path` to a resource file provided by Matplotlib.
 
     ``*args`` specify a path relative to the base data path.
     """
@@ -989,7 +989,7 @@ def _combine_masks(*args):
     Masks are obtained from all arguments of the correct length
     in categories 1, 2, and 4; a point is bad if masked in a masked
     array or if it is a nan or inf.  No attempt is made to
-    extract a mask from categories 2 and 4 if :meth:`np.isfinite`
+    extract a mask from categories 2 and 4 if `numpy.isfinite`
     does not yield a Boolean array.  Category 3 is included to
     support RGB or RGBA ndarrays, which are assumed to have only
     valid values and which are passed through unchanged.
@@ -1243,9 +1243,9 @@ def _compute_conf_interval(data, med, iqr, bootstrap):
     return bxpstats
 
 
-# The ls_mapper maps short codes for line style to their full name used by
-# backends; the reverse mapper is for mapping full names to short ones.
+#: Maps short codes for line style to their full name used by backends.
 ls_mapper = {'-': 'solid', '--': 'dashed', '-.': 'dashdot', ':': 'dotted'}
+#: Maps full names for line styles used by backends to their short codes.
 ls_mapper_r = {v: k for k, v in ls_mapper.items()}
 
 
@@ -1349,7 +1349,7 @@ def _reshape_2D(X, name):
     Use Fortran ordering to convert ndarrays and lists of iterables to lists of
     1D arrays.
 
-    Lists of iterables are converted by applying `np.asanyarray` to each of
+    Lists of iterables are converted by applying `numpy.asanyarray` to each of
     their elements.  1D ndarrays are returned in a singleton list containing
     them.  2D ndarrays are converted to the list of their *columns*.
 
@@ -2104,6 +2104,8 @@ def _warn_external(message, category=None):
     function back to `warnings.warn`, i.e. ``cbook._warn_external =
     warnings.warn`` (or ``functools.partial(warnings.warn, stacklevel=2)``,
     etc.).
+
+    :meta public:
     """
     frame = sys._getframe()
     for stacklevel in itertools.count(1):  # lgtm[py/unused-loop-variable]
