Documentation Link

No response

Problem

Per this discussion #27158 (comment), I (maybe other folk) are a bit confused on what the "do not edit" comments in pyplot mean given that boilerplate.py is never run automatically. Consensus seems to be that the process should be when changing the signature of a pyplot function, run boilerplate.py and commit those changes but that's not documented anywhere.

Suggested improvement

More clearly document using boilerplate.py by:

1. changing the Autogen message to "generated by biolerplate.py, do not edit"
   

   matplotlib/tools/boilerplate.py

   Lines 61 to 64 in b86e331

   	AUTOGEN_MSG = """
   	# Autogenerated by boilerplate.py. Do not edit as changes will be lost."""

2. change the comment at the top of pyplot to something like "plotting signatures are generated by boilerplate.py, rerun when changing signatures and commit the changes
   

   matplotlib/lib/matplotlib/pyplot.py

   Lines 1 to 2 in b86e331

   	# Note: The first part of this file can be modified in place, but the latter
   	# part is autogenerated by the boilerplate.py script.

3. add something like (note: this rst may be incorrect) to the coding guideline.

When a function in the :doc:`pyplot  API<doc/api/pyplot_summary>`, run :file:`lib/matplotlib/test_pyplot.py::test_pyplot_up_to_date`. If the test fails and and you intended to change those signatures, run boilerplate.py and commit the changes