MEP 12: Gallery cleanup and reorganization #1623

Closed
wants to merge 35 commits into
from

4 participants

@tonysyu

This pull request lays the groundwork for reorganizing the Matplotlib gallery, as described in MEP 12. To that end, this PR creates a new set of (tentatively-named) sections in the gallery. In addition, a few examples are cleaned up and moved to these new sections to demonstrate the clean up guidelines.

tonysyu added some commits Dec 18, 2012
@tonysyu tonysyu STY: Refactor string formatting/templating 31c4b57
@tonysyu tonysyu Clean-up and move scatter_demo a16e793
@tonysyu tonysyu Cleanup and move fill_demo a22ed53
@tonysyu tonysyu Cleanup and move pie_demo 48caac8
@tonysyu tonysyu Cleanup and move errorbar_demo.
Split demo in to two different examples
7f1887b
@tonysyu tonysyu Cleanup and move fill_demo2
Rename fill_demo2 to fill_demo_features to clarify purpose
b10a877
@tonysyu tonysyu Cleanup and move histogram_demo 6995e54
@tonysyu tonysyu Cleanup and move hinton_demo 48fab58
@tonysyu tonysyu Cleanup and move image_demo3.py
* Rename to imshow_demo
* Add smaller version of lena image saved as a numpy binary so that use doesn't require PIL
e9bfbb9
@tonysyu tonysyu DOC: Minor rewording 87aba29
@tonysyu tonysyu 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`.
c0f42d7
@tonysyu tonysyu Cleanup and move subplot_demo e244d9b
@tonysyu tonysyu Update example section titles 002ca7a
@tonysyu tonysyu Cleanup and move unicode_demo 402b301
@tonysyu tonysyu Consolidate histogram examples 529d9f7
@tonysyu tonysyu Cleanup and move vertical_ticklabels demo 6acc43a
@tonysyu tonysyu Cleanup and move clippath_demo 7f7c013
@tonysyu tonysyu Rename imshow_demo to image_demo ab417eb
@tonysyu tonysyu Cleanup and move polar_bar demo 5a77ad8
@tonysyu tonysyu Cleanup and move polar scatter demo e4dce4e
@tonysyu tonysyu Cleanup and move text themes demo cc18501
@tonysyu tonysyu Cleanup and move path_patch demo d02d560
@tonysyu tonysyu Clean up and move integral demo ec8a487
@tonysyu tonysyu Extract spines_demo_bounds from spine_placement_demo acc69cc
@tonysyu tonysyu Extract spines_demo from spine_placement_demo 800deb4
@tonysyu tonysyu Cleanup integral_demo edce62b
@tonysyu tonysyu Cleanup and move dash_control demo 405cbc5
@tonysyu tonysyu Clean up and move color_cycle demo 30a85ba
@tonysyu tonysyu Tweak subplot layout to prevent label clipping 7175e06
@tonysyu tonysyu Add colormap references based on show_colormaps 5020952
@tonysyu tonysyu Clean up and move artist demo fae23d6
@tonysyu tonysyu Clean up and move streamplot demos abfdea4
@tonysyu tonysyu Combine colormap reference examples 8f4be5b
@tonysyu tonysyu Clean up and move barh_demo 917c329
@pelson pelson and 1 other commented on an outdated diff Dec 28, 2012
doc/sphinxext/gen_gallery.py
@@ -1,37 +1,76 @@
# -*- 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}')
+custom_titles = {'pylab_examples' : 'pylab examples',
@pelson
Matplotlib Developers member
pelson added a line comment Dec 28, 2012

Seems a little redundant. Perhaps this dictionary could go in the conf.py?

@tonysyu
tonysyu added a line comment Dec 30, 2012

Good point. Fixed in latest commit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mdboom
Matplotlib Developers member

This looks great. I wonder what the best way to get the rest of the mechanical work done is? I'd suggest merging this PR once any kinks or details are worked out, and then dividing up the gallery examples among some volunteers on the mailing list to update to the new conventions and organization.

@NelleV

This is awesome! I think this is going to help users a lot. Thanks for doing this work.

@tonysyu

@NelleV Thanks. Good luck on MEP10. (PS. We miss you over at scikit-image:)

@mdboom Thanks for the feedback. I'm not certain what you mean by mechanical work. The mechanical part for me was checking for and renaming references to examples that I moved. Other than that, I didn't find anything too mechanical. Unless you mean the clean up itself. It might be nice to just have a script that automates some of the more common clean ups. That said, I don't remember anything that was very common amongst the examples that I cleaned up.

As for kinks: I still think the section names that I added could be improved. Some of the sections are too coarse, some are too fine. I guess that's unavoidable. It might also be nice to have more succinct section names. (For example, "lines, bars, and markers" probably deserve a better name. Also, do they really go together? I'd say yes, but I'm not completely convinced.)

@NelleV

@tonysyu I don't do vision anymore: . But you've got Andy contributing now

One thing I would love to see, but probably adds a large amount of work, is titles to examples like there is on scikit-image. I think it helps the user (and sometimes the developper itself) understanding why the example is there, and it makes the page easily searchable.

@mdboom
Matplotlib Developers member

@tonysu: Yes, I meant what you thought. Mainly the work of categorizing the rest of the examples and putting them in to shape that satisfy the new guidelines in MEP 12. It's not terribly mechanical, I guess -- and least not easy to automate. But it's a lot of work, and if there's an easy way to divide the work, that might be the best way to get it done.

As for the category names: they didn't strike me as terribly bad, and anything is an improvement over the current situation where many are grouped only by implementation style. I think perfect might be the enemy of the good on this one, and maybe we proceed with these and further divide the categories later if the need arises.

@mdboom mdboom referenced this pull request Jan 16, 2013
Closed

Use sublots in examples #1598

@tonysyu

@mdboom Good point on the category names. They'd be easy to change, and if nothing better jumps out, it's probably best just go with what's here.

As for automation, I think any mechanical work would be small compared to everything else. For example, I think most of the work is removing unnecessary customization, writing a good summary of the demo in the module docstring, combining/splitting examples from/into multiple files, etc.

@pelson
Matplotlib Developers member

Uh, oh - I'd forgotten about this big PR. Looks like there could be a couple of nasty merges as a result of this going stale. @tonysyu - are you going to be able to pick this up before release date (end of May)?

@tonysyu

Thanks for pinging me on this. I should have some time to work on this (depending on the amount of work). Any hints on what changes may cause merge issues? Also, do the matplotlib-devs prefer merging changes from master (and resolving conflicts) or rebasing?

@mdboom
Matplotlib Developers member

I generally prefer rebasing -- it makes the resulting history in the main project look cleaner. I hope the conflicts aren't too disastrous, but I haven't really looked.

@tonysyu

Sounds good. I'll try rebasing tonight. Let's hope it's not too painful. :P

@pelson
Matplotlib Developers member

Let's hope it's not too painful. :P

I find that rebasing, when a conflict is identified with multiple commits, results in conflicts at each of the commits during rebase (I hope that makes sense). If you find this is the case, I'd be prepared to accept a merge in this PR, or alternatively a PR for each commit here (or you could squash the commits into just a few commits)...

Sorry for the brain dump! HTH

@mdboom
Matplotlib Developers member

@pelson: Yes, that's true. When I run into that case (where a rebase causes conflicts at each step), I squash commits first, then rebase on master. I still think that's better than doing a merge in terms of the end result.

@tonysyu

See PR #1924

@mdboom
Matplotlib Developers member

Closed in favor of #1924.

@mdboom mdboom closed this Apr 19, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment