matplotlib · QuLogic · Jan 19, 2023 · Jan 18, 2023 · Jan 18, 2023 · Jan 19, 2023
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -812,9 +812,15 @@ to create a gallery of images in the :file:`/doc/gallery` and
 :file:`/doc/tutorials` directories respectively.  To exclude an example
 from having an plot generated insert "sgskip" somewhere in the filename.
 
+
+Formatting the example
+----------------------
+
 The format of these files is relatively straightforward.  Properly
 formatted comment blocks are treated as ReST_ text, the code is
-displayed, and figures are put into the built page.
+displayed, and figures are put into the built page.  Matplotlib uses the
+``# %%`` section separator so that IDEs will identify "code cells" to make
+it easy to re-run sub-sections of the example.
 
 For instance the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
 example is generated from
@@ -853,7 +859,7 @@ Tutorials are made with the exact same mechanism, except they are longer, and
 typically have more than one comment block (i.e.
 :doc:`/tutorials/introductory/quick_start`).  The first comment block
 can be the same as the example above.  Subsequent blocks of ReST text
-are delimited by a line of ``###`` characters:
+are delimited by the line ``# %%`` :
 
 .. code-block:: python
 
@@ -868,7 +874,7 @@ are delimited by a line of ``###`` characters:
     ax.grid()
     plt.show()
 
-    ##########################################################################
+    # %%
     # Second plot
     # ===========
     #
@@ -887,7 +893,7 @@ bottom as follows
 
 .. code-block:: python
 
-    ###############################################################################
+    # %%
     #
     # .. admonition:: References
     #

diff --git a/examples/animation/animated_histogram.py b/examples/animation/animated_histogram.py
@@ -21,7 +21,7 @@
 data = np.random.randn(1000)
 n, _ = np.histogram(data, HIST_BINS)
 
-###############################################################################
+# %%
 # To animate the histogram, we need an ``animate`` function, which generates
 # a random set of numbers and updates the heights of rectangles. We utilize a
 # python closure to track an instance of `.BarContainer` whose `.Rectangle`
@@ -39,7 +39,7 @@ def animate(frame_number):
         return bar_container.patches
     return animate
 
-###############################################################################
+# %%
 # Using :func:`~matplotlib.pyplot.hist` allows us to get an instance of
 # `.BarContainer`, which is a collection of `.Rectangle` instances. Calling
 # ``prepare_animation`` will define ``animate`` function working with supplied

diff --git a/examples/animation/multiple_axes.py b/examples/animation/multiple_axes.py
@@ -70,7 +70,7 @@ def animate(i):
 
 plt.show()
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

diff --git a/examples/axes_grid1/demo_axes_hbox_divider.py b/examples/axes_grid1/demo_axes_hbox_divider.py
@@ -33,7 +33,7 @@
 
 plt.show()
 
-###############################################################################
+# %%
 # Using a `.VBoxDivider` to arrange subplots.
 #
 # Note that both axes' location are adjusted so that they have

diff --git a/examples/axes_grid1/demo_fixed_size_axes.py b/examples/axes_grid1/demo_fixed_size_axes.py
@@ -8,7 +8,7 @@
 
 from mpl_toolkits.axes_grid1 import Divider, Size
 
-###############################################################################
+# %%
 
 
 fig = plt.figure(figsize=(6, 6))
@@ -26,7 +26,7 @@
 
 ax.plot([1, 2, 3])
 
-###############################################################################
+# %%
 
 
 fig = plt.figure(figsize=(6, 6))

diff --git a/examples/axes_grid1/inset_locator_demo.py b/examples/axes_grid1/inset_locator_demo.py
@@ -5,7 +5,7 @@
 
 """
 
-###############################################################################
+# %%
 # The `.inset_locator`'s `~.inset_locator.inset_axes` allows
 # easily placing insets in the corners of the axes by specifying a width and
 # height and optionally a location (loc) that accepts locations as codes,
@@ -43,7 +43,7 @@
 plt.show()
 
 
-###############################################################################
+# %%
 # The parameters *bbox_to_anchor* and *bbox_transform* can be used for a more
 # fine-grained control over the inset position and size or even to position
 # the inset at completely arbitrary positions.
@@ -100,7 +100,7 @@
 plt.show()
 
 
-###############################################################################
+# %%
 # In the above the axes transform together with 4-tuple bounding boxes has been
 # used as it mostly is useful to specify an inset relative to the axes it is
 # an inset to. However, other use cases are equally possible. The following

diff --git a/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py b/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py
@@ -17,7 +17,7 @@
 
 make_axes_area_auto_adjustable(ax)
 
-###############################################################################
+# %%
 
 fig = plt.figure()
 ax1 = fig.add_axes([0, 0, 1, 0.5])
@@ -31,7 +31,7 @@
 make_axes_area_auto_adjustable(ax1, pad=0.1, use_axes=[ax1, ax2])
 make_axes_area_auto_adjustable(ax2, pad=0.1, use_axes=[ax1, ax2])
 
-###############################################################################
+# %%
 
 fig = plt.figure()
 ax1 = fig.add_axes([0, 0, 1, 1])

diff --git a/examples/axes_grid1/scatter_hist_locatable_axes.py b/examples/axes_grid1/scatter_hist_locatable_axes.py
@@ -63,7 +63,7 @@
 
 plt.show()
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

diff --git a/examples/axes_grid1/simple_axes_divider1.py b/examples/axes_grid1/simple_axes_divider1.py
@@ -18,7 +18,7 @@ def label_axes(ax, text):
                    left=False, labelleft=False)
 
 
-##############################################################################
+# %%
 # Fixed axes sizes; fixed paddings.
 
 fig = plt.figure(figsize=(6, 6))
@@ -42,7 +42,7 @@ def label_axes(ax, text):
 ax4 = fig.add_axes(rect, axes_locator=div.new_locator(nx=2, nx1=4, ny=0))
 label_axes(ax4, "nx=2, nx1=4, ny=0")
 
-##############################################################################
+# %%
 # Axes sizes that scale with the figure size; fixed paddings.
 
 fig = plt.figure(figsize=(6, 6))

diff --git a/examples/axisartist/demo_floating_axes.py b/examples/axisartist/demo_floating_axes.py
@@ -145,7 +145,7 @@ def setup_axes3(fig, rect):
     return ax1, aux_ax
 
 
-##########################################################
+# %%
 fig = plt.figure(figsize=(8, 4))
 fig.subplots_adjust(wspace=0.3, left=0.05, right=0.95)
 

diff --git a/examples/color/color_by_yvalue.py b/examples/color/color_by_yvalue.py
@@ -22,7 +22,7 @@
 ax.plot(t, smiddle, t, slower, t, supper)
 plt.show()
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

diff --git a/examples/color/color_cycle_default.py b/examples/color/color_cycle_default.py
@@ -40,7 +40,7 @@
 
 plt.show()
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

diff --git a/examples/color/color_demo.py b/examples/color/color_demo.py
@@ -61,7 +61,7 @@
 
 plt.show()
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

diff --git a/examples/color/colorbar_basics.py b/examples/color/colorbar_basics.py
@@ -45,7 +45,7 @@
 cbar.minorticks_on()
 plt.show()
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

diff --git a/examples/color/colormap_reference.py b/examples/color/colormap_reference.py
@@ -68,7 +68,7 @@ def plot_color_gradients(cmap_category, cmap_list):
     plot_color_gradients(cmap_category, cmap_list)
 
 
-###############################################################################
+# %%
 # .. _reverse-cmap:
 #
 # Reversed colormaps
@@ -83,7 +83,7 @@ def plot_color_gradients(cmap_category, cmap_list):
 # The built-in reversed colormaps are generated using `.Colormap.reversed`.
 # For an example, see :ref:`reversing-colormap`
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

diff --git a/examples/color/custom_cmap.py b/examples/color/custom_cmap.py
@@ -108,7 +108,7 @@
 Z = np.cos(X) * np.sin(Y) * 10
 
 
-###############################################################################
+# %%
 # Colormaps from a list
 # ---------------------
 
@@ -126,7 +126,7 @@
     fig.colorbar(im, ax=ax)
 
 
-###############################################################################
+# %%
 # Custom colormaps
 # ----------------
 
@@ -202,14 +202,14 @@
 }
 
 
-###############################################################################
+# %%
 # Now we will use this example to illustrate 2 ways of
 # handling custom colormaps.
 # First, the most direct and explicit:
 
 blue_red1 = LinearSegmentedColormap('BlueRed1', cdict1)
 
-###############################################################################
+# %%
 # Second, create the map explicitly and register it.
 # Like the first method, this method works with any kind
 # of Colormap, not just
@@ -219,7 +219,7 @@
 mpl.colormaps.register(LinearSegmentedColormap('BlueRed3', cdict3))
 mpl.colormaps.register(LinearSegmentedColormap('BlueRedAlpha', cdict4))
 
-###############################################################################
+# %%
 # Make the figure, with 4 subplots:
 
 fig, axs = plt.subplots(2, 2, figsize=(6, 9))
@@ -264,7 +264,7 @@
 
 plt.show()
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

diff --git a/examples/color/named_colors.py b/examples/color/named_colors.py
@@ -73,21 +73,21 @@ def plot_colortable(colors, *, ncols=4, sort_colors=True):
 
     return fig
 
-#############################################################################
+# %%
 # -----------
 # Base colors
 # -----------
 
 plot_colortable(mcolors.BASE_COLORS, ncols=3, sort_colors=False)
 
-#############################################################################
+# %%
 # ---------------
 # Tableau Palette
 # ---------------
 
 plot_colortable(mcolors.TABLEAU_COLORS, ncols=2, sort_colors=False)
 
-#############################################################################
+# %%
 # ----------
 # CSS Colors
 # ----------
@@ -96,7 +96,7 @@ def plot_colortable(colors, *, ncols=4, sort_colors=True):
 plot_colortable(mcolors.CSS4_COLORS)
 plt.show()
 
-#############################################################################
+# %%
 # -----------
 # XKCD Colors
 # -----------

diff --git a/examples/event_handling/cursor_demo.py b/examples/event_handling/cursor_demo.py
@@ -72,7 +72,7 @@ def on_mouse_move(self, event):
 fig.canvas.mpl_connect('motion_notify_event', cursor.on_mouse_move)
 
 
-##############################################################################
+# %%
 # Faster redrawing using blitting
 # """""""""""""""""""""""""""""""
 # This technique stores the rendered plot as a background image. Only the
@@ -153,7 +153,7 @@ def on_mouse_move(self, event):
 fig.canvas.mpl_connect('motion_notify_event', blitted_cursor.on_mouse_move)
 
 
-##############################################################################
+# %%
 # Snapping to data points
 # """""""""""""""""""""""
 # The following cursor snaps its position to the data points of a `.Line2D`

diff --git a/examples/event_handling/ginput_manual_clabel_sgskip.py b/examples/event_handling/ginput_manual_clabel_sgskip.py
@@ -26,7 +26,7 @@ def tellme(s):
     plt.title(s, fontsize=16)
     plt.draw()
 
-##################################################
+# %%
 # Define a triangle by clicking three points
 
 
@@ -59,7 +59,7 @@ def tellme(s):
         p.remove()
 
 
-##################################################
+# %%
 # Now contour according to distance from triangle
 # corners - just an example
 
@@ -79,7 +79,7 @@ def f(x, y, pts):
 tellme('Use mouse to select contour label locations, middle button to finish')
 CL = plt.clabel(CS, manual=True)
 
-##################################################
+# %%
 # Now do a zoom
 
 tellme('Now do a nested zoom, click to begin')
-Original file line number
+Diff line change
@@ Expand Up / @@ -70,7 +70,7 @@ def animate(i): @@
     plt.show()
-    #############################################################################
+    # %%
     #
     # .. admonition:: References
     #
@@ Expand Down @@