All examples should be MEP12/sphinx-gallery compliant

[NelleV]

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

[WeatherGod]

Caveat... except for the examples that are purposely demonstrating the
pyplot or pylab interface, and has the proper context explaining when it is
ok.

But yes, the default should be the OO interface.

On Fri, Sep 30, 2016 at 2:53 PM, Nelle Varoquaux notifications@github.com
wrote:

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#7206, or mute the thread
https://github.com/notifications/unsubscribe-auth/AARy-MURSgYG0wgsVOoyQi0aDzXhOULVks5qvVqkgaJpZM4KLZqJ
.

[NelleV]

Sure. I'll make sure these don't appear in the list that is yet to be :)

[bjonnh]

Started working on that (NumFocus meetup Chicago), can anyone have a look at that commit:
bjonnh@904f079

Specific question being:

• I've seen that the files should be renamed to plot_foo if they generate a plot, is that really the case?
• Can I split examples when they show two different features (in that case SubPlotZero and set_axisline_style)?

I would appreciate some comments on that see if I can do the other examples like that

[bjonnh]

You'll find some more here:
https://github.com/bjonnh/matplotlib/commits/MEP12_NumFocus_Chicago

[NelleV]

Hi @bjonnh

I missed your message… Sorry for the late reply.

Renaming examples to plot will allow the plots to be shown in the gallery. Else, a default image will be displayed (an example can be seen here)

You can definitely split the examples if they showcase different features! Working on this is actually a good occasion to work a bit on our very long list of examples.

[NelleV]

I am giving up on the migration to sphinx-gallery.
The original goal was to make our documentation build system more robust but there doesn't seem to be a consensus on what this means.

I am thus closing this pull request. I apologize to everyone who've attempted to help me on this.

[petehuang]

@NelleV can you point us to where we can help push the discussion on this?

[tacaswell]

@NelleV Disagreement about merging minor changes to make.py does not mean there is broad disagreement about moving to sphinx-gallery or the long term goal of modernizing the documentation build system.

[yinleon]

working on:

• mplot3d/lorenz_attractor.py X
• pylab_examples/fill_between_demo.py X
• mplot3d/mixed_subplots_demo.py X
• mplot3d/offset_demo.py X
• mplot3d/lines3d_demo.py X
• pylab_examples/mri_demo.py X
• pylab_examples/geo_demo.py X
• text_labels_and_annotations/rainbow_text.py X
• event_handling/resample.py X
• event_handling/pipong.py X
• event_handling/poly_editor.py X
• event_handling/keypress_demo.py X
• pylab_examples/log_test.py X
• pylab_examples/bar_stacked.py X
• pylab_examples/dolphin.py X

in PR 8109

• misc/contour_manual.py
• pylab_examples/log_bar.py

[mitchnegus]

working on

• mplot3d/2dcollections3d_demo.py
• mplot3d/bars3d_demo.py
• mplot3d/hist3d_demo.py
• mplot3d/pathpatch3d_demo.py
• mplot3d/polys3d_demo.py

in PR #8233

[choldgraf]

I believe that these are all completed now, so we can probably close this issue