8000 Fix doc build to search in new example sections. · matplotlib/matplotlib@c0f42d7 · GitHub
[go: up one dir, main page]
Skip to content

Commit c0f42d7

Browse files
tonysyutonysyu
committed
Fix doc build to search in new example sections.
Add new sphinx config variable `mpl_example_sections` and use this list in both `gen_gallery.py` and `gen_rst.py`.
1 parent 87aba29 commit c0f42d7

File tree

6 files changed

+99
-28
lines changed

6 files changed

+99
-28
lines changed

‎doc/conf.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,23 @@
8282

8383
plot_formats = [('png', 80), ('hires.png', 200), ('pdf', 50)]
8484

85+
# Subdirectories in 'examples/' directory of package
86+
mpl_example_sections = ('lines_bars_and_markers',
87+
'shapes_and_collections',
88+
'statistics',
89+
'images_contours_and_fields',
90+
'pie_and_polar_charts',
91+
'text_labels_and_annotations',
92+
'ticks_and_spines',
93+
'subplots_axes_and_figures',
94+
'specialty_plots',
95+
'showcase',
96+
'reference',
97+
'api', 'pylab_examples',
98+
'mplot3d', 'axes_grid',
99+
'units', 'widgets')
100+
101+
85102
# Github extension
86103

87104
github_project_url = "http://github.com/matplotlib/matplotlib/"

‎doc/sphinxext/gen_gallery.py‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,12 @@
44
import glob
55
import warnings
66

7+
import sphinx.errors
8+
79
import matplotlib.image as image
810

11+
12+
exclude_example_sections = ['units']
913
multiimage = re.compile('(.*?)(_\d\d){1,2}')
1014

1115

@@ -64,6 +68,10 @@ def gen_gallery(app, doctree):
6468
outdir = app.builder.outdir
6569
rootdir = 'plot_directive/mpl_examples'
6670

71+
example_sections = list(app.builder.config.mpl_example_sections)
72+
for section in exclude_example_sections:
73+
example_sections.remove(section)
74+
6775
# images we want to skip for the gallery because they are an unusual
6876
# size that doesn't layout well in a table, or because they may be
6977
# redundant with other images or uninteresting
@@ -77,9 +85,8 @@ def gen_gallery(app, doctree):
7785
thumbnails = {}
7886
rows = []
7987
toc_rows = []
80-
dirs = ('api', 'pylab_examples', 'mplot3d', 'widgets', 'axes_grid' )
8188

82-
for subdir in dirs :
89+
for subdir in example_sections:
8390
title = custom_titles.get(subdir, subdir)
8491
rows.append(header_template.format(title=title, section=subdir))
8592
toc_rows.append(toc_template.format(section=subdir))
@@ -155,3 +162,8 @@ def gen_gallery(app, doctree):
155162

156163
def setup(app):
157164
app.connect('env-updated', gen_gallery)
165+
166+
try: # multiple plugins may use mpl_example_sections
167+
app.add_config_value('mpl_example_sections', [], True)
168+
except sphinx.errors.ExtensionError:
169+
pass # mpl_example_sections already defined

‎doc/sphinxext/gen_rst.py‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,17 @@
22
generate the rst files for the examples by iterating over the pylab examples
33
"""
44
from __future__ import print_function
5-
import os, glob
65

76
import os
87
import re
98
import sys
10-
fileList = []
9+
10+
import sphinx.errors
11+
12+
13+
exclude_example_sections = ['widgets']
14+
noplot_regex = re.compile(r"#\s*-\*-\s*noplot\s*-\*-")
15+
1116

1217
def out_of_date(original, derived):
1318
"""
@@ -21,14 +26,17 @@ def out_of_date(original, derived):
2126
return (not os.path.exists(derived) or
2227
os.stat(derived).st_mtime < os.stat(original).st_mtime)
2328

24-
noplot_regex = re.compile(r"#\s*-\*-\s*noplot\s*-\*-")
25-
2629
def generate_example_rst(app):
2730
rootdir = os.path.join(app.builder.srcdir, 'mpl_examples')
2831
exampledir = os.path.join(app.builder.srcdir, 'examples')
2932
if not os.path.exists(exampledir):
3033
os.makedirs(exampledir)
3134

35+
example_sections = list(app.builder.config.mpl_example_sections)
36+
for section in exclude_example_sections:
37+
example_sections.remove(section)
38+
39+
3240
datad = {}
3341
for root, subFolders, files in os.walk(rootdir):
3442
for fname in files:
@@ -114,13 +122,8 @@ def generate_example_rst(app):
114122

115123
fhsubdirIndex.write(' %s <%s>\n'%(os.path.basename(basename),rstfile))
116124

117-
do_plot = (subdir in ('api',
118-
'pylab_examples',
119-
'units',
120-
'mplot3d',
121-
'axes_grid',
122-
) and
123-
not noplot_regex.search(contents))
125+
do_plot = (subdir in example_sections
126+
and not noplot_regex.search(contents))
124127
if not do_plot:
125128
fhstatic = file(outputfile, 'w')
126129
fhstatic.write(contents)
@@ -157,3 +160,8 @@ def generate_example_rst(app):
157160

158161
def setup(app):
159162
app.connect('builder-inited', generate_example_rst)
163+
164+
try: # multiple plugins may use mpl_example_sections
165+
app.add_config_value('mpl_example_sections', [], True)
166+
except sphinx.errors.ExtensionError:
167+
pass # mpl_example_sections already defined

‎doc/users/screenshots.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Histograms
3232
The :func:`~matplotlib.pyplot.hist` command automatically generates
3333
histograms and will return the bin counts or probabilities
3434

35-
.. plot:: mpl_examples/pylab_examples/histogram_demo.py
35+
.. plot:: mpl_examples/statistics/histogram_demo_features.py
3636

3737

3838
.. _screenshots_path_demo:
@@ -103,7 +103,7 @@ or more wedges out from the center of the pie, and a shadow effect.
103103
Take a close look at the attached code that produced this figure; nine
104104
lines of code.
105105

106-
.. plot:: mpl_examples/pylab_examples/pie_demo.py
106+
.. plot:: mpl_examples/pie_and_polar_charts/pie_demo_features.py
107107

108108
.. _screenshots_table_demo:
109109

@@ -153,7 +153,7 @@ The :func:`~matplotlib.pyplot.fill` command lets you
153153
plot filled polygons. Thanks to Andrew Straw for providing this
154154
function
155155

156-
.. plot:: mpl_examples/pylab_examples/fill_demo.py
156+
.. plot:: mpl_examples/lines_bars_and_markers/fill_demo.py
157157

158158

159159
.. _screenshots_date_demo:

‎examples/tests/backend_driver.py‎

Lines changed: 43 additions & 9 deletions
DB7C
Original file line numberDiff line numberDiff line change
@@ -20,21 +20,62 @@
2020
switches with a --.
2121
"""
2222

23-
import os, time, sys, glob, string
23+
import os
24+
import time
25+
import sys
26+
import glob
2427
from optparse import OptionParser
28+
2529
import matplotlib.rcsetup as rcsetup
2630
from matplotlib.cbook import Bunch, dedent
2731

32+
2833
all_backends = list(rcsetup.all_backends) # to leave the original list alone
2934

3035
# actual physical directory for each dir
31-
dirs = dict(pylab = os.path.join('..', 'pylab_examples'),
36+
dirs = dict(files=os.path.join('..', 'lines_bars_and_markers'),
37+
shapes=os.path.join('..', 'shapes_and_collections'),
38+
images=os.path.join('..', 'images_contours_and_fields'),
39+
pie=os.path.join('..', 'pie_and_polar_charts'),
40+
text=os.path.join('..', 'text_labels_and_annotations'),
41+
ticks=os.path.join('..', 'ticks_and_spines'),
42+
subplots=os.path.join('..', 'subplots_axes_and_figures'),
43+
specialty=os.path.join('..', 'specialty_plots'),
44+
showcase=os.path.join('..', 'showcase'),
45+
reference=os.path.join('..', 'reference'),
46+
pylab = os.path.join('..', 'pylab_examples'),
3247
api = os.path.join('..', 'api'),
3348
units = os.path.join('..', 'units'),
3449
mplot3d = os.path.join('..', 'mplot3d'))
3550

51+
3652
# files in each dir
3753
files = dict()
54+
55+
files['lines'] = [
56+
'fill_demo.py',
57+
'fill_demo_features.py',
58+
]
59+
60+
files['shapes'] = [
61+
'scatter_demo.py',
62+
]
63+
64+
files['images'] = [
65+
'imshow_demo.py',
66+
]
67+
68+
69+
files['statistics'] = [
70+
'errorbar_demo.py',
71+
'errorbar_demo_features.py',
72+
'histogram_demo_features.py',
73+
]
74+
75+
files['pie'] = [
76+
'pie_demo.py',
77+
]
78+
3879
files['pylab'] = [
3980
'accented_text.py',
4081
'alignment_test.py',
@@ -86,7 +127,6 @@
86127
'ellipse_demo.py',
87128
'ellipse_rotated.py',
88129
'equal_aspect_ratio.py',
89-
'errorbar_demo.py',
90130
'errorbar_limits.py',
91131
'fancyarrow_demo.py',
92132
'fancybox_demo.py',
@@ -96,8 +136,6 @@
96136
'figlegend_demo.py',
97137
'figure_title.py',
98138
'fill_between_demo.py',
99-
'fill_demo.py',
100-
'fill_demo2.py',
101139
'fill_spiral.py',
102140
'finance_demo.py',
103141
'findobj_demo.py',
@@ -111,14 +149,12 @@
111149
'hexbin_demo.py',
112150
'hexbin_demo2.py',
113151
'hist_colormapped.py',
114-
'histogram_demo.py',
115152
'histogram_demo_extended.py',
116153
'hline_demo.py',
117154

118155
'image_clip_path.py',
119156
'image_demo.py',
120157
'image_demo2.py',
121-
'image_demo3.py',
122158
'image_interp.py',
123159
'image_masked.py',
124160
'image_nonuniform.py',
@@ -158,7 +194,6 @@
158194
'pcolor_demo2.py',
159195
'pcolor_log.py',
160196
'pcolor_small.py',
161-
'pie_demo.py',
162197
'pie_demo2.py',
163198
'plotfile_demo.py',
164199
'polar_bar.py',
@@ -172,7 +207,6 @@
172207
'quadmesh_demo.py',
173208
'quiver_demo.py',
174209
'scatter_custom_symbol.py',
175-
'scatter_demo.py',
176210
'scatter_demo2.py',
177211
'scatter_masked.py',
178212
'scatter_profile.py',

‎lib/matplotlib/axes.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5367,7 +5367,7 @@ def errorbar(self, x, y, yerr=None, xerr=None,
53675367
53685368
**Example:**
53695369
5370-
.. plot:: mpl_examples/pylab_examples/errorbar_demo.py
5370+
.. plot:: mpl_examples/statistics/errorbar_demo.py
53715371
53725372
"""
53735373

@@ -6697,7 +6697,7 @@ def fill(self, *args, **kwargs):
66976697
66986698
**Example:**
66996699
6700-
.. plot:: mpl_examples/pylab_examples/fill_demo.py
6700+
.. plot:: mpl_examples/lines_bars_and_markers/fill_demo.py
67016701
67026702
"""
67036703
if not self._hold:
@@ -7976,7 +7976,7 @@ def hist(self, x, bins=10, range=None, normed=False, weights=None,
79767976
79777977
**Example:**
79787978
7979-
.. plot:: mpl_examples/pylab_examples/histogram_demo.py
7979+
.. plot:: mpl_examples/statistics/histogram_demo_features.py
79807980
79817981
"""
79827982
if not self._hold:

0 commit comments

Comments
 (0)
0