doc: Switch to matplotlib's existing plot_directive.
doc: Remove unused Sphinx extension.
doc: Rebase gen_gallery to matplotlib 1.2.0.

matplotlib 1.2.0 is the current minimum required version. It's
unfortunate that it doesn't supply this extension itself, though.

Also, I made this more PEP8 compliant than the original.
doc: Use built-in Sphinx file-inclusion commands.
doc: Make gallery creation work on newer matplotlib.

Tested with matplotlib 1.3.1.
doc: Minor file writing changes.

Use the more modern `with` statement and not the old-style `file` type.
doc: Make random image display actually work.

Using the already-generated random_image.js, shuffle list of images, and
then pick the first 5 for display. Since the image paths are no longer
hard-coded, this should work with matplotlib 1.2 and 1.3+.
doc: Remove extraneous plt.show() calls.

The latest plot_directive splits at plt.show(), which breaks code that's
indented. There's really no benefit to these multiple show calls, so
I've just removed them.
doc: Make Sphinx extensions PEP8 compliant.
doc: Auto-generate figure IDs for linking.

This should fix the links from the front page's random image display.
doc: Make package sidebar smarter.

It needs to ignore a few more things, like private packages, tests,
sub-sub-packages, etc.
doc: Broadly categorize example plots.