Merge pull request matplotlib#30562 from timhoffm/doc-boilerplate

DOC: improve description of boilerplate.py

Author: timhoffm

lib/matplotlib/pyplot.py

@@ -1,5 +1,9 @@
-# Note: The first part of this file can be modified in place, but the latter
-# part is autogenerated by the boilerplate.py script.
+# Note: The first part of this file is hand-written and must be edited
+# in-place. The second part, starting with
+#   ### REMAINING CONTENT GENERATED BY boilerplate.py ###
+# is generated by the script boilerplate.py. It must not be edited here
+# because all changes will be overwritten by the next run of the script.
+# For more information see the description in boilerplate.py.
 
 """
 `matplotlib.pyplot` is a state-based interface to matplotlib. It provides

tools/boilerplate.py

@@ -1,12 +1,19 @@
 """
 Script to autogenerate pyplot wrappers.
 
-When this script is run, the current contents of pyplot are
-split into generatable and non-generatable content (via the magic header
-:attr:`PYPLOT_MAGIC_HEADER`) and the generatable content is overwritten.
-Hence, the non-generatable content should be edited in the pyplot.py file
-itself, whereas the generatable content must be edited via templates in
-this file.
+pyplot.py consists of two parts: a hand-written part at the top, and an
+automatically generated part at the bottom, starting with the comment
+
+  ### REMAINING CONTENT GENERATED BY boilerplate.py ###
+
+This script generates the automatically generated part of pyplot.py. It
+consists of colormap setter functions and wrapper functions for methods
+of Figure and Axes. Whenever the API of one of the wrapped methods changes,
+this script has to be rerun to keep pyplot.py up to date.
+
+The test ``lib/matplotlib/test_pyplot.py::test_pyplot_up_to_date`` checks
+that the autogenerated part of pyplot.py is up to date. It will fail in the
+case of an API mismatch and remind the developer to rerun this script.
 """
 
 # Although it is possible to dynamically generate the pyplot functions at