From 21864d1ac8aa6ebbbbfee7808f59b4aed8648cbd Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Thu, 27 Jul 2023 00:57:28 +0200
Subject: [PATCH] Move pylab documentation to its own module page

Previously, pylab was not listed under modules, but the module docstring
(and thus also the target of pylab links) wa on the API Reference top
page.

While pylab is discouraged, it's still a regular module and should be
handled as such. Even more importantly, by removing the pylab section
from the API reference top page, we de-emphasize it. Note, that pylab is
still mentioned in the more in-depth backend discussion at
https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html
---
 doc/api/index.rst       |  7 +------
 doc/api/pylab.rst       |  6 ++++++
 lib/matplotlib/pylab.py | 23 ++++++++++++++---------
 3 files changed, 21 insertions(+), 15 deletions(-)
 create mode 100644 doc/api/pylab.rst

diff --git a/doc/api/index.rst b/doc/api/index.rst
index 8ad4e2e9ea1a..644842ee70ae 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -80,12 +80,6 @@ Further reading:
 
 .. _api-index:
 
-The pylab API (discouraged)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: pylab
-   :no-members:
-
 Modules
 -------
 
@@ -162,3 +156,4 @@ Alphabetical list of modules:
    toolkits/mplot3d.rst
    toolkits/axes_grid1.rst
    toolkits/axisartist.rst
+   pylab.rst
diff --git a/doc/api/pylab.rst b/doc/api/pylab.rst
new file mode 100644
index 000000000000..184d0b578c71
--- /dev/null
+++ b/doc/api/pylab.rst
@@ -0,0 +1,6 @@
+*********
+``pylab``
+*********
+
+.. automodule:: pylab
+   :no-members:
diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py
index ebd65655bbed..7fe492b5f332 100644
--- a/lib/matplotlib/pylab.py
+++ b/lib/matplotlib/pylab.py
@@ -1,14 +1,19 @@
 """
+`pylab` is a historic interface that is no longer recommended.
+
+Its original purpose was to mimic a MATLAB-like way of working by importing all
+functions into the global namespace.
+
+The intended usage pattern was ``from pylab import *``. This imports all functions
+from `matplotlib.pyplot`, `numpy`, `numpy.fft`, `numpy.linalg`, `numpy.random`, and
+some additional functions into the global namespace.
+
 .. warning::
-   Since heavily importing into the global namespace may result in unexpected
-   behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot`
-   instead.
-
-`pylab` is a module that includes `matplotlib.pyplot`, `numpy`, `numpy.fft`,
-`numpy.linalg`, `numpy.random`, and some additional functions, all within
-a single namespace. Its original purpose was to mimic a MATLAB-like way
-of working by importing all functions into the global namespace. This is
-considered bad style nowadays.
+   The wildcard import will overwrite some builtin functions (e.g. the builtin `sum`
+   will be replaced by `numpy.sum`). This can lead to unexpected behavior.
+
+   The use of pylab is strongly discouraged. Use `matplotlib.pyplot` instead.
+
 """
 
 from matplotlib.cbook import flatten, silent_list