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`.

doc/conf.py

@@ -82,6 +82,23 @@
 
 plot_formats = [('png', 80), ('hires.png', 200), ('pdf', 50)]
 
+# Subdirectories in 'examples/' directory of package
+mpl_example_sections = ('lines_bars_and_markers',
+                        'shapes_and_collections',
+                        'statistics',
+                        'images_contours_and_fields',
+                        'pie_and_polar_charts',
+                        'text_labels_and_annotations',
+                        'ticks_and_spines',
+                        'subplots_axes_and_figures',
+                        'specialty_plots',
+                        'showcase',
+                        'reference',
+                        'api', 'pylab_examples',
+                        'mplot3d', 'axes_grid',
+                        'units', 'widgets')
+
+
 # Github extension
 
 github_project_url = "http://github.com/matplotlib/matplotlib/"

doc/sphinxext/gen_gallery.py

@@ -4,8 +4,12 @@
 import glob
 import warnings
 
+import sphinx.errors
+
 import matplotlib.image as image
 
+
+exclude_example_sections = ['units']
 multiimage = re.compile('(.*?)(_\d\d){1,2}')
 
 
@@ -64,6 +68,10 @@ def gen_gallery(app, doctree):
     outdir = app.builder.outdir
     rootdir = 'plot_directive/mpl_examples'
 
+    example_sections = list(app.builder.config.mpl_example_sections)
+    for section in exclude_example_sections:
+        example_sections.remove(section)
+
     # images we want to skip for the gallery because they are an unusual
     # size that doesn't layout well in a table, or because they may be
     # redundant with other images or uninteresting
@@ -77,9 +85,8 @@ def gen_gallery(app, doctree):
     thumbnails = {}
     rows = []
     toc_rows = []
-    dirs = ('api', 'pylab_examples', 'mplot3d', 'widgets', 'axes_grid' )
 
-    for subdir in dirs :
+    for subdir in example_sections:
         title = custom_titles.get(subdir, subdir)
         rows.append(header_template.format(title=title, section=subdir))
         toc_rows.append(toc_template.format(section=subdir))
@@ -155,3 +162,8 @@ def gen_gallery(app, doctree):
 
 def setup(app):
     app.connect('env-updated', gen_gallery)
+
+    try: # multiple plugins may use mpl_example_sections
+        app.add_config_value('mpl_example_sections', [], True)
+    except sphinx.errors.ExtensionError:
+        pass # mpl_example_sections already defined

doc/sphinxext/gen_rst.py

@@ -2,12 +2,17 @@
 generate the rst files for the examples by iterating over the pylab examples
 """
 from __future__ import print_function
-import os, glob
 
 import os
 import re
 import sys
-fileList = []
+
+import sphinx.errors
+
+
+exclude_example_sections = ['widgets']
+noplot_regex = re.compile(r"#\s*-\*-\s*noplot\s*-\*-")
+
 
 def out_of_date(original, derived):
     """
@@ -21,14 +26,17 @@ def out_of_date(original, derived):
     return (not os.path.exists(derived) or
             os.stat(derived).st_mtime < os.stat(original).st_mtime)
 
-noplot_regex = re.compile(r"#\s*-\*-\s*noplot\s*-\*-")
-
 def generate_example_rst(app):
     rootdir = os.path.join(app.builder.srcdir, 'mpl_examples')
     exampledir = os.path.join(app.builder.srcdir, 'examples')
     if not os.path.exists(exampledir):
         os.makedirs(exampledir)
 
+    example_sections = list(app.builder.config.mpl_example_sections)
+    for section in exclude_example_sections:
+        example_sections.remove(section)
+
+
     datad = {}
     for root, subFolders, files in os.walk(rootdir):
         for fname in files:
@@ -114,13 +122,8 @@ def generate_example_rst(app):
 
             fhsubdirIndex.write('    %s <%s>\n'%(os.path.basename(basename),rstfile))
 
-            do_plot = (subdir in ('api',
-                                  'pylab_examples',
-                                  'units',
-                                  'mplot3d',
-                                  'axes_grid',
-                                  ) and
-                       not noplot_regex.search(contents))
+            do_plot = (subdir in example_sections
+                       and not noplot_regex.search(contents))
             if not do_plot:
                 fhstatic = file(outputfile, 'w')
                 fhstatic.write(contents)
@@ -157,3 +160,8 @@ def generate_example_rst(app):
 
 def setup(app):
     app.connect('builder-inited', generate_example_rst)
+
+    try: # multiple plugins may use mpl_example_sections
+        app.add_config_value('mpl_example_sections', [], True)
+    except sphinx.errors.ExtensionError:
+        pass # mpl_example_sections already defined

doc/users/screenshots.rst

@@ -32,7 +32,7 @@ Histograms
 The :func:`~matplotlib.pyplot.hist` command automatically generates
 histograms and will return the bin counts or probabilities
 
-.. plot:: mpl_examples/pylab_examples/histogram_demo.py
+.. plot:: mpl_examples/statistics/histogram_demo_features.py
 
 
 .. _screenshots_path_demo:
@@ -103,7 +103,7 @@ or more wedges out from the center of the pie, and a shadow effect.
 Take a close look at the attached code that produced this figure; nine
 lines of code.
 
-.. plot:: mpl_examples/pylab_examples/pie_demo.py
+.. plot:: mpl_examples/pie_and_polar_charts/pie_demo_features.py
 
 .. _screenshots_table_demo:
 
@@ -153,7 +153,7 @@ The :func:`~matplotlib.pyplot.fill` command lets you
 plot filled polygons.  Thanks to Andrew Straw for providing this
 function
 
-.. plot:: mpl_examples/pylab_examples/fill_demo.py
+.. plot:: mpl_examples/lines_bars_and_markers/fill_demo.py
 
 
 .. _screenshots_date_demo:

examples/tests/backend_driver.py

@@ -20,21 +20,62 @@
 switches with a --.
 """
 
-import os, time, sys, glob, string
+import os
+import time
+import sys
+import glob
 from optparse import OptionParser
+
 import matplotlib.rcsetup as rcsetup
 from matplotlib.cbook import Bunch, dedent
 
+
 all_backends = list(rcsetup.all_backends)  # to leave the original list alone
 
 # actual physical directory for each dir
-dirs = dict(pylab = os.path.join('..', 'pylab_examples'),
+dirs = dict(files=os.path.join('..', 'lines_bars_and_markers'),
+            shapes=os.path.join('..', 'shapes_and_collections'),
+            images=os.path.join('..', 'images_contours_and_fields'),
+            pie=os.path.join('..', 'pie_and_polar_charts'),
+            text=os.path.join('..', 'text_labels_and_annotations'),
+            ticks=os.path.join('..', 'ticks_and_spines'),
+            subplots=os.path.join('..', 'subplots_axes_and_figures'),
+            specialty=os.path.join('..', 'specialty_plots'),
+            showcase=os.path.join('..', 'showcase'),
+            reference=os.path.join('..', 'reference'),
+            pylab = os.path.join('..', 'pylab_examples'),
             api = os.path.join('..', 'api'),
             units = os.path.join('..', 'units'),
             mplot3d = os.path.join('..', 'mplot3d'))
 
+
 # files in each dir
 files = dict()
+
+files['lines'] = [
+    'fill_demo.py',
+    'fill_demo_features.py',
+    ]
+
+files['shapes'] = [
+    'scatter_demo.py',
+    ]
+
+files['images'] = [
+    'imshow_demo.py',
+    ]
+
+
+files['statistics'] = [
+    'errorbar_demo.py',
+    'errorbar_demo_features.py',
+    'histogram_demo_features.py',
+    ]
+
+files['pie'] = [
+    'pie_demo.py',
+    ]
+
 files['pylab'] = [
     'accented_text.py',
     'alignment_test.py',
@@ -86,7 +127,6 @@
     'ellipse_demo.py',
     'ellipse_rotated.py',
     'equal_aspect_ratio.py',
-    'errorbar_demo.py',
     'errorbar_limits.py',
     'fancyarrow_demo.py',
     'fancybox_demo.py',
@@ -96,8 +136,6 @@
     'figlegend_demo.py',
     'figure_title.py',
     'fill_between_demo.py',
-    'fill_demo.py',
-    'fill_demo2.py',
     'fill_spiral.py',
     'finance_demo.py',
     'findobj_demo.py',
@@ -111,14 +149,12 @@
     'hexbin_demo.py',
     'hexbin_demo2.py',
     'hist_colormapped.py',
-    'histogram_demo.py',
     'histogram_demo_extended.py',
     'hline_demo.py',
 
     'image_clip_path.py',
     'image_demo.py',
     'image_demo2.py',
-    'image_demo3.py',
     'image_interp.py',
     'image_masked.py',
     'image_nonuniform.py',
@@ -158,7 +194,6 @@
     'pcolor_demo2.py',
     'pcolor_log.py',
     'pcolor_small.py',
-    'pie_demo.py',
     'pie_demo2.py',
     'plotfile_demo.py',
     'polar_bar.py',
@@ -172,7 +207,6 @@
     'quadmesh_demo.py',
     'quiver_demo.py',
     'scatter_custom_symbol.py',
-    'scatter_demo.py',
     'scatter_demo2.py',
     'scatter_masked.py',
     'scatter_profile.py',

lib/matplotlib/axes.py

@@ -5367,7 +5367,7 @@ def errorbar(self, x, y, yerr=None, xerr=None,
 
         **Example:**
 
-        .. plot:: mpl_examples/pylab_examples/errorbar_demo.py
+        .. plot:: mpl_examples/statistics/errorbar_demo.py
 
         """
 
@@ -6697,7 +6697,7 @@ def fill(self, *args, **kwargs):
 
         **Example:**
 
-        .. plot:: mpl_examples/pylab_examples/fill_demo.py
+        .. plot:: mpl_examples/lines_bars_and_markers/fill_demo.py
 
         """
         if not self._hold:
@@ -7976,7 +7976,7 @@ def hist(self, x, bins=10, range=None, normed=False, weights=None,
 
         **Example:**
 
-        .. plot:: mpl_examples/pylab_examples/histogram_demo.py
+        .. plot:: mpl_examples/statistics/histogram_demo_features.py
 
         """
         if not self._hold: