Merge pull request matplotlib#25021 from tacaswell/doc/sg_splitter

Doc: sg section separator

Author: QuLogic

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
     #

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

examples/animation/multiple_axes.py

@@ -70,7 +70,7 @@ def animate(i):
 
 plt.show()
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

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

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))

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

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])

examples/axes_grid1/scatter_hist_locatable_axes.py

@@ -63,7 +63,7 @@
 
 plt.show()
 
-#############################################################################
+# %%
 #
 # .. admonition:: References
 #

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))

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)