Issue 1:
sphinx-gallery was originally created from matplotlib's code to create a sphinx gallery but has since been packaged properly, and evolved to have more features and be more robust to sphinx build systems.

It has a couple of nice features that come out of the box including better formatting of gallery examples docstrings (see [1]), easy linking to documentation examples (specifically, deals with converting examples to rst and updating those, while our builds symlinks or copies stuff around, which makes moving to the Makefile system a bit more painful on our end).

I suggest that we integrate sphinx-gallery in several steps to make the pull request smaller and easier to review:

All gallery examples should be documented with a docstring that includes a title at the top of the file.

All example folders containing plots should also contain a readme file

Example files that plot an element should be renamed plot_filename.py to be rendered properly by sphinx-gallery.

[1]_ http://scikit-learn.org/stable/auto_examples/plot_isotonic_regression.html#sphx-glr-auto-examples-plot-isotonic-regression-py

Issue 2:
We are slowly moving to MEP12 compliant examples.

sphinx-gallery was originally created from matplotlib's code to create a sphinx gallery but has since been packaged properly, and evolved to have more features and be more robust to sphinx build systems.

It has a couple of nice features that come out of the box including better formatting of gallery examples docstrings (see [1]), easy linking to documentation examples (specifically, deals with converting examples to rst and updating those, while our builds symlinks or copies stuff around, which makes moving to the Makefile system a bit more painful on our end).

Here are some steps to get our examples to build with sphinx-gallery:

All gallery examples should be documented with a docstring that includes a title at the top of the file.

All example folders containing plots should also contain a readme file

[1]_ http://scikit-learn.org/stable/auto_examples/plot_isotonic_regression.html#sphx-glr-auto-examples-plot-isotonic-regression-py

Examples of MEP12-compliant plots

Fill demo

Documentation:

http://matplotlib.org/devdocs/devel/MEP/MEP12.html

List of elements that need to be updated:

Axes grid1

axes_grid1/demo_axes_divider.py

axes_grid1/demo_axes_grid2.py

axes_grid1/demo_axes_grid.py

axes_grid1/demo_axes_hbox_divider.py

axes_grid1/demo_axes_rgb.py

axes_grid1/demo_colorbar_with_inset_locator.py

axes_grid1/demo_edge_colorbar.py

axes_grid1/demo_imagegrid_aspect.py

axes_grid1/inset_locator_demo2.py

axes_grid1/inset_locator_demo.py

axes_grid1/make_room_for_ylabel_using_axesgrid.py

axes_grid1/parasite_simple2.py

axes_grid1/scatter_hist.py

axes_grid1/simple_anchored_artists.py

axes_grid1/simple_axesgrid2.py

axes_grid1/simple_axesgrid.py

axes_grid1/simple_axisline4.py

Event handling

event_handling/close_event.py

event_handling/data_browser.py

event_handling/figure_axes_enter_leave.py

event_handling/idle_and_timeout.py

event_handling/keypress_demo.py

event_handling/lasso_demo.py

event_handling/legend_picking.py

event_handling/looking_glass.py

event_handling/path_editor.py

event_handling/pick_event_demo2.py

event_handling/pick_event_demo.py

event_handling/pipong.py

event_handling/poly_editor.py

event_handling/pong_gtk.py

event_handling/resample.py

event_handling/test_mouseclicks.py

event_handling/timers.py

event_handling/trifinder_event_demo.py

event_handling/viewlims.py

event_handling/zoom_window.py

misc

misc/contour_manual.py

misc/font_indexing.py

misc/ftface_props.py

misc/image_thumbnail.py

misc/multiprocess.py

misc/rasterization_demo.py

misc/rc_traits.py

misc/rec_groupby_demo.py

misc/rec_join_demo.py

misc/sample_data_demo.py

misc/svg_filter_line.py

misc/svg_filter_pie.py

misc/tight_bbox_test.py

mplot3d

mplot3d/2dcollections3d_demo.py

mplot3d/bars3d_demo.py

mplot3d/contour3d_demo2.py

mplot3d/contour3d_demo3.py

mplot3d/contour3d_demo.py

mplot3d/contourf3d_demo2.py

mplot3d/contourf3d_demo.py

mplot3d/custom_shaded_3d_surface.py

mplot3d/hist3d_demo.py

mplot3d/lines3d_demo.py

mplot3d/lorenz_attractor.py

mplot3d/mixed_subplots_demo.py

mplot3d/offset_demo.py

mplot3d/pathpatch3d_demo.py

mplot3d/polys3d_demo.py

mplot3d/quiver3d_demo.py

mplot3d/rotate_axes3d_demo.py

mplot3d/scatter3d_demo.py

mplot3d/subplot3d_demo.py

mplot3d/surface3d_demo2.py

mplot3d/surface3d_demo3.py

mplot3d/surface3d_demo.py

mplot3d/surface3d_radial_demo.py

mplot3d/text3d_demo.py

mplot3d/tricontour3d_demo.py

mplot3d/tricontourf3d_demo.py

mplot3d/trisurf3d_demo2.py

mplot3d/trisurf3d_demo.py

mplot3d/wire3d_animation_demo.py

mplot3d/wire3d_demo.py

mplot3d/wire3d_zero_stride.py

Pylab examples

pylab_examples/accented_text.py

pylab_examples/agg_buffer.py

pylab_examples/agg_buffer_to_array.py

pylab_examples/alignment_test.py

pylab_examples/anchored_artists.py

pylab_examples/animation_demo.py

pylab_examples/annotation_demo2.py

pylab_examples/annotation_demo3.py

pylab_examples/annotation_demo.py

pylab_examples/anscombe.py

pylab_examples/arctest.py

pylab_examples/arrow_demo.py

pylab_examples/arrow_simple_demo.py

pylab_examples/aspect_loglog.py

pylab_examples/axes_demo.py

pylab_examples/axes_props.py

pylab_examples/axes_zoom_effect.py

pylab_examples/axhspan_demo.py

pylab_examples/axis_equal_demo.py

pylab_examples/barb_demo.py

pylab_examples/barchart_demo2.py

pylab_examples/barchart_demo.py

pylab_examples/barcode_demo.py

pylab_examples/bar_stacked.py�

pylab_examples/boxplot_demo2.py

pylab_examples/boxplot_demo3.py

pylab_examples/boxplot_demo.py

pylab_examples/broken_axis.py

pylab_examples/broken_barh.py

pylab_examples/centered_ticklabels.py

pylab_examples/cohere_demo.py

pylab_examples/colorbar_tick_labelling_demo.py

pylab_examples/color_by_yvalue.py

pylab_examples/color_demo.py

pylab_examples/colours.py

pylab_examples/contour_corner_mask.py

pylab_examples/contour_demo.py

pylab_examples/contourf_demo.py

pylab_examples/contourf_hatching.py

pylab_examples/contour_image.py

pylab_examples/contour_label_demo.py

pylab_examples/coords_demo.py

pylab_examples/coords_report.py

pylab_examples/csd_demo.py

pylab_examples/cursor_demo.py

pylab_examples/custom_cmap.py

pylab_examples/custom_figure_class.py

pylab_examples/customize_rc.py

pylab_examples/custom_ticker1.py

pylab_examples/dashpointlabel.py

pylab_examples/data_helper.py

pylab_examples/date_demo_convert.py

pylab_examples/date_demo_rrule.py

pylab_examples/date_index_formatter.py

pylab_examples/demo_agg_filter.py

pylab_examples/demo_annotation_box.py

pylab_examples/demo_bboximage.py

pylab_examples/demo_ribbon_box.py

pylab_examples/demo_text_path.py

pylab_examples/demo_text_rotation_mode.py

pylab_examples/demo_tight_layout.py

pylab_examples/dolphin.py

pylab_examples/ellipse_collection.py

pylab_examples/ellipse_demo.py

pylab_examples/ellipse_rotated.py

pylab_examples/equal_aspect_ratio.py

pylab_examples/errorbar_limits.py

pylab_examples/errorbar_subsample.py

pylab_examples/eventcollection_demo.py

pylab_examples/eventplot_demo.py

pylab_examples/fancyarrow_demo.py

pylab_examples/fancybox_demo2.py

pylab_examples/fancybox_demo.py

pylab_examples/fancytextbox_demo.py

pylab_examples/figimage_demo.py

pylab_examples/figlegend_demo.py

pylab_examples/figure_title.py

pylab_examples/fill_between_demo.py

pylab_examples/fill_betweenx_demo.py

pylab_examples/fill_spiral.py

pylab_examples/findobj_demo.py

pylab_examples/fonts_demo_kw.py

pylab_examples/fonts_demo.py

pylab_examples/font_table_ttf.py

pylab_examples/ganged_plots.py

pylab_examples/geo_demo.py

pylab_examples/ginput_demo.py

pylab_examples/ginput_manual_clabel.py

pylab_examples/gradient_bar.py

pylab_examples/griddata_demo.py

pylab_examples/hatch_demo.py

pylab_examples/hexbin_demo2.py

pylab_examples/hexbin_demo.py

pylab_examples/hist2d_demo.py

pylab_examples/hist2d_log_demo.py

pylab_examples/hist_colormapped.py

pylab_examples/histogram_percent_demo.py

pylab_examples/hyperlinks.py

pylab_examples/image_clip_path.py

pylab_examples/image_demo2.py

pylab_examples/image_demo.py

pylab_examples/image_interp.py

pylab_examples/image_masked.py

pylab_examples/image_nonuniform.py

pylab_examples/image_origin.py

pylab_examples/image_slices_viewer.py

pylab_examples/interp_demo.py

pylab_examples/invert_axes.py

pylab_examples/layer_images.py

pylab_examples/leftventricle_bulleye.py

pylab_examples/legend_demo2.py

pylab_examples/legend_demo3.py

pylab_examples/legend_demo4.py

pylab_examples/legend_demo5.py

pylab_examples/legend_demo6.py

pylab_examples/line_collection2.py

pylab_examples/line_collection.py

pylab_examples/load_converter.py

pylab_examples/loadrec.py

pylab_examples/log_bar.py

pylab_examples/log_demo.py

pylab_examples/logo.py

pylab_examples/log_test.py

pylab_examples/major_minor_demo1.py

pylab_examples/major_minor_demo2.py

pylab_examples/manual_axis.py

pylab_examples/marker_path.py

pylab_examples/markevery_demo.py

pylab_examples/masked_demo.py

pylab_examples/mathtext_demo.py

pylab_examples/mathtext_examples.py

pylab_examples/matshow.py

pylab_examples/movie_demo.py

pylab_examples/mri_demo.py

pylab_examples/mri_with_eeg.py

pylab_examples/multicolored_line.py

pylab_examples/multi_image.py

pylab_examples/multiline.py

pylab_examples/multipage_pdf.py

pylab_examples/multiple_figs_demo.py

pylab_examples/multiple_yaxis_with_spines.py

pylab_examples/nan_test.py

pylab_examples/newscalarformatter_demo.py

pylab_examples/patheffect_demo.py

pylab_examples/pcolor_demo.py

pylab_examples/pcolor_log.py

pylab_examples/pcolor_small.py

pylab_examples/pie_demo2.py

pylab_examples/plotfile_demo.py

pylab_examples/polar_demo.py

pylab_examples/polar_legend.py

pylab_examples/print_stdout.py

pylab_examples/psd_demo2.py

pylab_examples/psd_demo3.py

pylab_examples/psd_demo_complex.py

pylab_examples/psd_demo.py

pylab_examples/pythonic_matplotlib.py

pylab_examples/quadmesh_demo.py

pylab_examples/quiver_demo.py

pylab_examples/scatter_custom_symbol.py

pylab_examples/scatter_demo2.py

pylab_examples/scatter_hist.py

pylab_examples/scatter_masked.py

pylab_examples/scatter_profile.py

pylab_examples/scatter_star_poly.py

pylab_examples/scatter_symbol.py

pylab_examples/set_and_get.py

pylab_examples/shading_example.py

pylab_examples/shared_axis_across_figures.py

pylab_examples/shared_axis_demo.py

pylab_examples/simple_plot.py

pylab_examples/specgram_demo.py

pylab_examples/spectrum_demo.py

pylab_examples/spine_placement_demo.py

pylab_examples/spy_demos.py

pylab_examples/stackplot_demo2.py

pylab_examples/stackplot_demo.py

pylab_examples/stem_plot.py

pylab_examples/step_demo.py

pylab_examples/stix_fonts_demo.py

pylab_examples/stock_demo.py

pylab_examples/subplot_demo.py

pylab_examples/subplots_adjust.py

pylab_examples/subplots_demo.py

pylab_examples/subplot_toolbar.py

pylab_examples/symlog_demo.py

pylab_examples/system_monitor.py

pylab_examples/table_demo.py

pylab_examples/tex_demo.py

pylab_examples/text_handles.py

pylab_examples/text_rotation.py

pylab_examples/text_rotation_relative_to_line.py

pylab_examples/tex_unicode_demo.py

pylab_examples/titles_demo.py

pylab_examples/toggle_images.py

pylab_examples/transoffset.py

pylab_examples/tricontour_demo.py

pylab_examples/tricontour_smooth_delaunay.py

pylab_examples/tricontour_smooth_user.py

pylab_examples/tricontour_vs_griddata.py

pylab_examples/trigradient_demo.py

pylab_examples/triinterp_demo.py

pylab_examples/tripcolor_demo.py

pylab_examples/triplot_demo.py

pylab_examples/usetex_baseline_test.py

pylab_examples/usetex_demo.py

pylab_examples/usetex_fonteffects.py

pylab_examples/vline_hline_demo.py

pylab_examples/webapp_demo.py

pylab_examples/xcorr_demo.py

pylab_examples/zorder_demo.py

Units

units/annotate_with_units.py

units/artist_tests.py

units/bar_demo2.py

units/bar_unit_demo.py

units/basic_units.py

units/ellipse_with_units.py

units/evans_test.py

units/radian_demo.py

units/units_sample.py

units/units_scatter.py

User interfaces

user_interfaces/embedding_in_gtk2.py

user_interfaces/embedding_in_gtk3_panzoom.py

user_interfaces/embedding_in_gtk3.py

user_interfaces/embedding_in_gtk.py

user_interfaces/embedding_in_qt4.py

user_interfaces/embedding_in_qt4_wtoolbar.py

user_interfaces/embedding_in_qt5.py

user_interfaces/embedding_in_tk2.py

user_interfaces/embedding_in_tk_canvas.py

user_interfaces/embedding_in_tk.py

user_interfaces/embedding_in_wx2.py

user_interfaces/embedding_in_wx3.py

user_interfaces/embedding_in_wx4.py

user_interfaces/embedding_in_wx5.py

user_interfaces/embedding_webagg.py

user_interfaces/fourier_demo_wx.py

user_interfaces/gtk_spreadsheet.py

user_interfaces/histogram_demo_canvasagg.py

user_interfaces/interactive2.py

user_interfaces/interactive.py

user_interfaces/lineprops_dialog_gtk.py

user_interfaces/mathtext_wx.py

user_interfaces/mpl_with_glade_316.py

user_interfaces/mpl_with_glade.py

user_interfaces/pylab_with_gtk.py

user_interfaces/rec_edit_gtk_custom.py

user_interfaces/rec_edit_gtk_simple.py

user_interfaces/svg_histogram.py

user_interfaces/svg_tooltip.py

user_interfaces/toolmanager.py

user_interfaces/wxcursor_demo.py

Widgets

widgets/buttons.py

widgets/check_buttons.py

widgets/cursor.py

widgets/lasso_selector_demo.py

widgets/menu.py

widgets/multicursor.py

widgets/radio_buttons.py

widgets/rectangle_selector.py

widgets/slider_demo.py

widgets/span_selector.py

widgets/textbox.py

Folders entirely finished

Statistics

Pie and polar charts

Animation

Color

Lines, bars and markers

Showcase

Speciality plots

Images, contours and fields

Subplots, axes and figures

Shapes and collections

Images, contours and fields

Axis Artist

Text, labels and annotations

Ticks & spines

Scales

Style sheets

API