matplotlib · tonysyu · Dec 18, 2012 · Dec 18, 2012 · Dec 18, 2012 · Dec 18, 2012
diff --git a/doc/conf.py b/doc/conf.py
@@ -82,6 +82,29 @@
 
 plot_formats = [('png', 80), ('hires.png', 200), ('pdf', 50)]
 
+# Subdirectories in 'examples/' directory of package and titles for gallery
+# TODO: Change to OrderedDict when Matplotlib drops support for Python < 2.7
+mpl_example_sections = (
+    ('lines_bars_and_markers', 'Lines, bars, and markers'),
+    ('shapes_and_collections', 'Shapes and collections'),
+    ('statistics', 'Statistical plots'),
+    ('images_contours_and_fields', 'Images, contours, and fields'),
+    ('pie_and_polar_charts', 'Pie and polar charts'),
+    ('color', 'Color'),
+    ('text_labels_and_annotations', 'Text, labels, and annotations'),
+    ('ticks_and_spines', 'Ticks and spines'),
+    ('subplots_axes_and_figures', 'Subplots, axes, and figures'),
+    ('specialty_plots', 'Specialty plots'),
+    ('showcase', 'Showcase'),
+    ('api', 'API'),
+    ('pylab_examples', 'pylab examples'),
+    ('mplot3d', 'mplot3d toolkit'),
+    ('axes_grid', 'axes_grid toolkit'),
+    ('units', 'units'),
+    ('widgets', 'widgets'),
+    )
+
+
 # Github extension
 
 github_project_url = "http://github.com/matplotlib/matplotlib/"

diff --git a/doc/sphinxext/gen_gallery.py b/doc/sphinxext/gen_gallery.py
@@ -1,44 +1,74 @@
 # -*- coding: UTF-8 -*-
+import os
+import re
+import glob
+import warnings
+
+import sphinx.errors
+
+import matplotlib.image as image
+
+
+exclude_example_sections = ['units']
+multiimage = re.compile('(.*?)(_\d\d){1,2}')
 
 # generate a thumbnail gallery of examples
-template = """\
-{%% extends "layout.html" %%}
-{%% set title = "Thumbnail gallery" %%}
+gallery_template = """\
+{{% extends "layout.html" %}}
+{{% set title = "Thumbnail gallery" %}}
 
 
-{%% block body %%}
+{{% block body %}}
 
 <h3>Click on any image to see full size image and source code</h3>
 <br/>
 
-<li><a class="reference internal" href="#">Gallery</a><ul>
-%s
-</ul>
+<li><a class="reference internal" href="#">Gallery</a>
+    <ul>
+    {toc}
+    </ul>
 </li>
 
-%s
-{%% endblock %%}
+{gallery}
+
+{{% endblock %}}
 """
 
-import os, glob, re, sys, warnings
-import matplotlib.image as image
+header_template = """\
+<div class="section" id="{section}">
+<h4>
+    {title}<a class="headerlink" href="#{section}" title="Permalink to this headline">¶</a>
+</h4>"""
+
+link_template = """\
+<a href="{link}"><img src="{thumb}" border="0" alt="{basename}"/></a>
+"""
+
+toc_template = """\
+<li><a class="reference internal" href="#{section}">{title}</a></li>"""
 
-multiimage = re.compile('(.*?)(_\d\d){1,2}')
 
 def make_thumbnail(args):
     image.thumbnail(args[0], args[1], 0.3)
 
+
 def out_of_date(original, derived):
     return (not os.path.exists(derived) or
             os.stat(derived).st_mtime < os.stat(original).st_mtime)
 
+
 def gen_gallery(app, doctree):
     if app.builder.name != 'html':
         return
 
     outdir = app.builder.outdir
     rootdir = 'plot_directive/mpl_examples'
 
+    example_sections = list(app.builder.config.mpl_example_sections)
+    for i, (subdir, title) in enumerate(example_sections):
+        if subdir in exclude_example_sections:
+            example_sections.pop(i)
+
     # 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
@@ -53,21 +83,9 @@ def gen_gallery(app, doctree):
     rows = []
     toc_rows = []
 
-    link_template = """\
-    <a href="%s"><img src="%s" border="0" alt="%s"/></a>
-    """
-
-    header_template = """<div class="section" id="%s">\
-    <h4>%s<a class="headerlink" href="#%s" title="Permalink to this headline">¶</a></h4>"""
-
-    toc_template = """\
-    <li><a class="reference internal" href="#%s">%s</a></li>"""
-
-    dirs = ('api', 'pylab_examples', 'mplot3d', 'widgets', 'axes_grid' )
-
-    for subdir in dirs :
-        rows.append(header_template % (subdir, subdir, subdir))
-        toc_rows.append(toc_template % (subdir, subdir))
+    for subdir, title in example_sections:
+        rows.append(header_template.format(title=title, section=subdir))
+        toc_rows.append(toc_template.format(title=title, section=subdir))
 
         origdir = os.path.join('build', rootdir, subdir)
         thumbdir = os.path.join(outdir, rootdir, subdir, 'thumbnails')
@@ -99,33 +117,34 @@ def gen_gallery(app, doctree):
             data.append((subdir, basename,
                          os.path.join(rootdir, subdir, 'thumbnails', filename)))
 
-
-
-
         for (subdir, basename, thumbfile) in data:
             if thumbfile is not None:
                 link = 'examples/%s/%s.html'%(subdir, basename)
-                rows.append(link_template%(link, thumbfile, basename))
+                rows.append(link_template.format(link=link,
+                                                 thumb=thumbfile,
+                                                 basename=basename))
 
         if len(data) == 0:
             warnings.warn("No thumbnails were found in %s" % subdir)
 
         # Close out the <div> opened up at the top of this loop
         rows.append("</div>")
 
-    content = template % ('\n'.join(toc_rows),
-                          '\n'.join(rows))
+    content = gallery_template.format(toc='\n'.join(toc_rows),
+                                      gallery='\n'.join(rows))
 
     # Only write out the file if the contents have actually changed.
     # Otherwise, this triggers a full rebuild of the docs
 
-    gallery_path = os.path.join(app.builder.srcdir, '_templates', 'gallery.html')
+    gallery_path = os.path.join(app.builder.srcdir,
+                                '_templates', 'gallery.html')
     if os.path.exists(gallery_path):
         fh = file(gallery_path, 'r')
         regenerate = fh.read() != content
         fh.close()
     else:
         regenerate = True
+
     if regenerate:
         fh = file(gallery_path, 'w')
         fh.write(content)
@@ -136,5 +155,11 @@ def gen_gallery(app, doctree):
         length=len(thumbnails)):
         image.thumbnail(key, thumbnails[key], 0.3)
 
+
 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
diff --git a/doc/sphinxext/gen_rst.py b/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,18 @@ 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 i, (subdir, title) in enumerate(example_sections):
+        if subdir in exclude_example_sections:
+            example_sections.pop(i)
+    example_subdirs, titles = zip(*example_sections)
+
     datad = {}
     for root, subFolders, files in os.walk(rootdir):
         for fname in files:
@@ -114,13 +123,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_subdirs
+                       and not noplot_regex.search(contents))
             if not do_plot:
                 fhstatic = file(outputfile, 'w')
                 fhstatic.write(contents)
@@ -157,3 +161,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
diff --git a/doc/users/image_tutorial.rst b/doc/users/image_tutorial.rst
@@ -228,7 +228,7 @@ object:
 
 There are many other colormap schemes available.  See the `list and
 images of the colormaps
-<http://matplotlib.org/examples/pylab_examples/show_colormaps.html>`_.
+<http://matplotlib.org/examples/color/colormaps_reference.html>`_.
 
 .. _`Color Bars`:
 

diff --git a/doc/users/screenshots.rst b/doc/users/screenshots.rst
@@ -22,7 +22,7 @@ Subplot demo
 Multiple regular axes (numrows by numcolumns) are created with the
 :func:`~matplotlib.pyplot.subplot` command.
 
-.. plot:: mpl_examples/pylab_examples/subplot_demo.py
+.. plot:: mpl_examples/subplots_axes_and_figures/subplot_demo.py
 
 .. _screenshots_histogram_demo:
 
@@ -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:
@@ -43,7 +43,7 @@ Path demo
 You can add arbitrary paths in matplotlib as of release 0.98.  See
 the :mod:`matplotlib.path`.
 
-.. plot:: mpl_examples/api/path_patch_demo.py
+.. plot:: mpl_examples/shapes_and_collections/path_patch_demo.py
 
 .. _screenshots_mplot3d_surface:
 
@@ -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:

diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -195,7 +195,7 @@ In addition to simply plotting the streamlines of the vector field,
 line widths of the streamlines to a separate parameter, such as the speed or
 local intensity of the vector field.
 
-.. plot:: mpl_examples/pylab_examples/streamplot_demo.py
+.. plot:: mpl_examples/images_contours_and_fields/streamplot_demo_features.py
 
 
 New hist functionality
@@ -442,7 +442,7 @@ Other improvements
 
 * Pim Schellart added a new colormap called "cubehelix".
   Sameer Grover also added a colormap called "coolwarm". See it and all
-  other colormaps :ref:`here <pylab_examples-show_colormaps>`.
+  other colormaps :ref:`here <color-colormaps_reference>`.
 
 * Many bug fixes and documentation improvements.