doc: Fix short documentation header line.
doc: Add newlines to fix Sphinx warnings.

reST requires newlines between blocks that change indentation. Sphinx
doesn't seem to mind, mostly, but it produces a lot of warnings if
they're missing.
doc: Add missing toctree entries.
Merge pull request #1355 from QuLogic/doc-updates

Documentation updates
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: Replace plt.show() calls with iplt.show().

The latest plot_directive splits at plt.show(), which breaks code that's
indented. The iris.plot.show alias still works with the testing
framework, but doesn't trigger this splitting.
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.