Skip to content

Commit 9c48e4b

Browse files
QuLogicQuLogic
authored
Merge pull request #25021 from tacaswell/doc/sg_splitter
Doc: sg section separator
2 parents be7ea76 + e5f0066 commit 9c48e4b

File tree

272 files changed

+835
-829
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

272 files changed

+835
-829
lines changed

‎doc/devel/documenting_mpl.rst

+10-4
Original file line numberDiff line numberDiff line change
@@ -812,9 +812,15 @@ to create a gallery of images in the :file:`/doc/gallery` and
812812
:file:`/doc/tutorials` directories respectively. To exclude an example
813813
from having an plot generated insert "sgskip" somewhere in the filename.
814814

815+
816+
Formatting the example
817+
----------------------
818+
815819
The format of these files is relatively straightforward. Properly
816820
formatted comment blocks are treated as ReST_ text, the code is
817-
displayed, and figures are put into the built page.
821+
displayed, and figures are put into the built page. Matplotlib uses the
822+
``# %%`` section separator so that IDEs will identify "code cells" to make
823+
it easy to re-run sub-sections of the example.
818824

819825
For instance the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
820826
example is generated from
@@ -853,7 +859,7 @@ Tutorials are made with the exact same mechanism, except they are longer, and
853859
typically have more than one comment block (i.e.
854860
:doc:`/tutorials/introductory/quick_start`). The first comment block
855861
can be the same as the example above. Subsequent blocks of ReST text
856-
are delimited by a line of ``###`` characters:
862+
are delimited by the line ``# %%`` :
857863

858864
.. code-block:: python
859865
@@ -868,7 +874,7 @@ are delimited by a line of ``###`` characters:
868874
ax.grid()
869875
plt.show()
870876
871-
##########################################################################
877+
# %%
872878
# Second plot
873879
# ===========
874880
#
@@ -887,7 +893,7 @@ bottom as follows
887893

888894
.. code-block:: python
889895
890-
###############################################################################
896+
# %%
891897
#
892898
# .. admonition:: References
893899
#

‎examples/animation/animated_histogram.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
data = np.random.randn(1000)
2222
n, _ = np.histogram(data, HIST_BINS)
2323

24-
###############################################################################
24+
# %%
2525
# To animate the histogram, we need an ``animate`` function, which generates
2626
# a random set of numbers and updates the heights of rectangles. We utilize a
2727
# python closure to track an instance of `.BarContainer` whose `.Rectangle`
@@ -39,7 +39,7 @@ def animate(frame_number):
3939
return bar_container.patches
4040
return animate
4141

42-
###############################################################################
42+
# %%
4343
# Using :func:`~matplotlib.pyplot.hist` allows us to get an instance of
4444
# `.BarContainer`, which is a collection of `.Rectangle` instances. Calling
4545
# ``prepare_animation`` will define ``animate`` function working with supplied

‎examples/animation/multiple_axes.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ def animate(i):
7070

7171
plt.show()
7272

73-
#############################################################################
73+
# %%
7474
#
7575
# .. admonition:: References
7676
#

‎examples/axes_grid1/demo_axes_hbox_divider.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333

3434
plt.show()
3535

36-
###############################################################################
36+
# %%
3737
# Using a `.VBoxDivider` to arrange subplots.
3838
#
3939
# Note that both axes' location are adjusted so that they have

‎examples/axes_grid1/demo_fixed_size_axes.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
from mpl_toolkits.axes_grid1 import Divider, Size
1010

11-
###############################################################################
11+
# %%
1212

1313

1414
fig = plt.figure(figsize=(6, 6))
@@ -26,7 +26,7 @@
2626

2727
ax.plot([1, 2, 3])
2828

29-
###############################################################################
29+
# %%
3030

3131

3232
fig = plt.figure(figsize=(6, 6))

‎examples/axes_grid1/inset_locator_demo.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
66
"""
77

8-
###############################################################################
8+
# %%
99
# The `.inset_locator`'s `~.inset_locator.inset_axes` allows
1010
# easily placing insets in the corners of the axes by specifying a width and
1111
# height and optionally a location (loc) that accepts locations as codes,
@@ -43,7 +43,7 @@
4343
plt.show()
4444

4545

46-
###############################################################################
46+
# %%
4747
# The parameters *bbox_to_anchor* and *bbox_transform* can be used for a more
4848
# fine-grained control over the inset position and size or even to position
4949
# the inset at completely arbitrary positions.
@@ -100,7 +100,7 @@
100100
plt.show()
101101

102102

103-
###############################################################################
103+
# %%
104104
# In the above the axes transform together with 4-tuple bounding boxes has been
105105
# used as it mostly is useful to specify an inset relative to the axes it is
106106
# an inset to. However, other use cases are equally possible. The following

‎examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717

1818
make_axes_area_auto_adjustable(ax)
1919

20-
###############################################################################
20+
# %%
2121

2222
fig = plt.figure()
2323
ax1 = fig.add_axes([0, 0, 1, 0.5])
@@ -31,7 +31,7 @@
3131
make_axes_area_auto_adjustable(ax1, pad=0.1, use_axes=[ax1, ax2])
3232
make_axes_area_auto_adjustable(ax2, pad=0.1, use_axes=[ax1, ax2])
3333

34-
###############################################################################
34+
# %%
3535

3636
fig = plt.figure()
3737
ax1 = fig.add_axes([0, 0, 1, 1])

‎examples/axes_grid1/scatter_hist_locatable_axes.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@
6363

6464
plt.show()
6565

66-
#############################################################################
66+
# %%
6767
#
6868
# .. admonition:: References
6969
#

‎examples/axes_grid1/simple_axes_divider1.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ def label_axes(ax, text):
1818
left=False, labelleft=False)
1919

2020

21-
##############################################################################
21+
# %%
2222
# Fixed axes sizes; fixed paddings.
2323

2424
fig = plt.figure(figsize=(6, 6))
@@ -42,7 +42,7 @@ def label_axes(ax, text):
4242
ax4 = fig.add_axes(rect, axes_locator=div.new_locator(nx=2, nx1=4, ny=0))
4343
label_axes(ax4, "nx=2, nx1=4, ny=0")
4444

45-
##############################################################################
45+
# %%
4646
# Axes sizes that scale with the figure size; fixed paddings.
4747

4848
fig = plt.figure(figsize=(6, 6))

‎examples/axisartist/demo_floating_axes.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ def setup_axes3(fig, rect):
145145
return ax1, aux_ax
146146

147147

148-
##########################################################
148+
# %%
149149
fig = plt.figure(figsize=(8, 4))
150150
fig.subplots_adjust(wspace=0.3, left=0.05, right=0.95)
151151

‎examples/color/color_by_yvalue.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
ax.plot(t, smiddle, t, slower, t, supper)
2323
plt.show()
2424

25-
#############################################################################
25+
# %%
2626
#
2727
# .. admonition:: References
2828
#

‎examples/color/color_cycle_default.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040

4141
plt.show()
4242

43-
#############################################################################
43+
# %%
4444
#
4545
# .. admonition:: References
4646
#

‎examples/color/color_demo.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@
6161

6262
plt.show()
6363

64-
#############################################################################
64+
# %%
6565
#
6666
# .. admonition:: References
6767
#

‎examples/color/colorbar_basics.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
cbar.minorticks_on()
4646
plt.show()
4747

48-
#############################################################################
48+
# %%
4949
#
5050
# .. admonition:: References
5151
#

‎examples/color/colormap_reference.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ def plot_color_gradients(cmap_category, cmap_list):
6868
plot_color_gradients(cmap_category, cmap_list)
6969

7070

71-
###############################################################################
71+
# %%
7272
# .. _reverse-cmap:
7373
#
7474
# Reversed colormaps
@@ -83,7 +83,7 @@ def plot_color_gradients(cmap_category, cmap_list):
8383
# The built-in reversed colormaps are generated using `.Colormap.reversed`.
8484
# For an example, see :ref:`reversing-colormap`
8585

86-
#############################################################################
86+
# %%
8787
#
8888
# .. admonition:: References
8989
#

‎examples/color/custom_cmap.py

+6-6
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@
108108
Z = np.cos(X) * np.sin(Y) * 10
109109

110110

111-
###############################################################################
111+
# %%
112112
# Colormaps from a list
113113
# ---------------------
114114

@@ -126,7 +126,7 @@
126126
fig.colorbar(im, ax=ax)
127127

128128

129-
###############################################################################
129+
# %%
130130
# Custom colormaps
131131
# ----------------
132132

@@ -202,14 +202,14 @@
202202
}
203203

204204

205-
###############################################################################
205+
# %%
206206
# Now we will use this example to illustrate 2 ways of
207207
# handling custom colormaps.
208208
# First, the most direct and explicit:
209209

210210
blue_red1 = LinearSegmentedColormap('BlueRed1', cdict1)
211211

212-
###############################################################################
212+
# %%
213213
# Second, create the map explicitly and register it.
214214
# Like the first method, this method works with any kind
215215
# of Colormap, not just
@@ -219,7 +219,7 @@
219219
mpl.colormaps.register(LinearSegmentedColormap('BlueRed3', cdict3))
220220
mpl.colormaps.register(LinearSegmentedColormap('BlueRedAlpha', cdict4))
221221

222-
###############################################################################
222+
# %%
223223
# Make the figure, with 4 subplots:
224224

225225
fig, axs = plt.subplots(2, 2, figsize=(6, 9))
@@ -264,7 +264,7 @@
264264

265265
plt.show()
266266

267-
#############################################################################
267+
# %%
268268
#
269269
# .. admonition:: References
270270
#

‎examples/color/named_colors.py

+4-4
Original file line numberDiff line numberDiff line change
@@ -73,21 +73,21 @@ def plot_colortable(colors, *, ncols=4, sort_colors=True):
7373

7474
return fig
7575

76-
#############################################################################
76+
# %%
7777
# -----------
7878
# Base colors
7979
# -----------
8080

8181
plot_colortable(mcolors.BASE_COLORS, ncols=3, sort_colors=False)
8282

83-
#############################################################################
83+
# %%
8484
# ---------------
8585
# Tableau Palette
8686
# ---------------
8787

8888
plot_colortable(mcolors.TABLEAU_COLORS, ncols=2, sort_colors=False)
8989

90-
#############################################################################
90+
# %%
9191
# ----------
9292
# CSS Colors
9393
# ----------
@@ -96,7 +96,7 @@ def plot_colortable(colors, *, ncols=4, sort_colors=True):
9696
plot_colortable(mcolors.CSS4_COLORS)
9797
plt.show()
9898

99-
#############################################################################
99+
# %%
100100
# -----------
101101
# XKCD Colors
102102
# -----------

‎examples/event_handling/cursor_demo.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ def on_mouse_move(self, event):
7272
fig.canvas.mpl_connect('motion_notify_event', cursor.on_mouse_move)
7373

7474

75-
##############################################################################
75+
# %%
7676
# Faster redrawing using blitting
7777
# """""""""""""""""""""""""""""""
7878
# This technique stores the rendered plot as a background image. Only the
@@ -153,7 +153,7 @@ def on_mouse_move(self, event):
153153
fig.canvas.mpl_connect('motion_notify_event', blitted_cursor.on_mouse_move)
154154

155155

156-
##############################################################################
156+
# %%
157157
# Snapping to data points
158158
# """""""""""""""""""""""
159159
# The following cursor snaps its position to the data points of a `.Line2D`

‎examples/event_handling/ginput_manual_clabel_sgskip.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ def tellme(s):
2626
plt.title(s, fontsize=16)
2727
plt.draw()
2828

29-
##################################################
29+
# %%
3030
# Define a triangle by clicking three points
3131

3232

@@ -59,7 +59,7 @@ def tellme(s):
5959
p.remove()
6060

6161

62-
##################################################
62+
# %%
6363
# Now contour according to distance from triangle
6464
# corners - just an example
6565

@@ -79,7 +79,7 @@ def f(x, y, pts):
7979
tellme('Use mouse to select contour label locations, middle button to finish')
8080
CL = plt.clabel(CS, manual=True)
8181

82-
##################################################
82+
# %%
8383
# Now do a zoom
8484

8585
tellme('Now do a nested zoom, click to begin')

0 commit comments

Comments
 (0)