From 7175d7c187d2ca72cc308df8f8b9c6379084e0df Mon Sep 17 00:00:00 2001
From: Ralf Gommers <rgommers@Ralf-Gommerss-iMac.local>
Date: Wed, 14 Oct 2009 00:24:43 +0200
Subject: [PATCH] Add support for MPL plots in the docs.

Both inline plots and plots from script files work.

Some things to keep in mind:
- for including scripts from docstrings, use prefix  "../plots/",
  for including scripts in a rst file, use "plots/".
  This is due to the docs being generated from the source/api folder.
- inline plots are not (yet) aware of variables being defined earlier
  in the Examples section.
- we now use the numpydoc sphinx extensions, the original MPL ones can not
  be used because they have no support for the make file and conf.py not
  being in the same folder.

There is one minor thing that does not work yet. The source code link for
plots does not work because for some reason the script files are not
copied to the build dir.
---
 doc/source/conf.py                  | 45 +++++++++++++++++++++++++++--
 doc/source/plots/show_collection.py | 28 ++++++++++++++++++
 scikits/image/io/collection.py      |  6 +++-
 3 files changed, 75 insertions(+), 4 deletions(-)
 create mode 100644 doc/source/plots/show_collection.py

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8ffd8cda..a4f13f68 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -19,14 +19,16 @@ import sys, os
 #sys.path.append(os.path.abspath('.'))
 
 curpath = os.path.dirname(__file__)
-sys.path.append(os.path.join(curpath, '../ext'))
+sys.path.append(os.path.join(curpath, '..', 'ext'))
 
 # -- General configuration -----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc',
-              'sphinx.ext.autosummary', 'sphinx.ext.inheritance_diagram']
+              'sphinx.ext.autosummary', 'sphinx.ext.inheritance_diagram',
+              'numpydoc.only_directives',
+              'numpydoc.plot_directive']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -115,7 +117,7 @@ html_theme = 'default'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+html_title = 'v%s documentation'%version
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
@@ -210,3 +212,40 @@ latex_documents = [
 
 # If false, no module index is generated.
 #latex_use_modindex = True
+
+# -----------------------------------------------------------------------------
+# Numpy extensions
+# -----------------------------------------------------------------------------
+# Make numpydoc to generate plots for example sections
+#numpydoc_use_plots = True
+
+# -----------------------------------------------------------------------------
+# Plots
+# -----------------------------------------------------------------------------
+plot_pre_code = """
+import numpy as np
+import matplotlib.pyplot as plt
+np.random.seed(0)
+"""
+plot_include_source = False
+plot_formats = [('png', 100), 'pdf']
+
+import math
+phi = (math.sqrt(5) + 1)/2
+
+import matplotlib
+matplotlib.rcParams.update({
+    'font.size': 8,
+    'axes.titlesize': 8,
+    'axes.labelsize': 8,
+    'xtick.labelsize': 8,
+    'ytick.labelsize': 8,
+    'legend.fontsize': 8,
+    'figure.figsize': (3*phi, 3),
+    'figure.subplot.bottom': 0.2,
+    'figure.subplot.left': 0.2,
+    'figure.subplot.right': 0.9,
+    'figure.subplot.top': 0.85,
+    'figure.subplot.wspace': 0.4,
+    'text.usetex': False,
+})
diff --git a/doc/source/plots/show_collection.py b/doc/source/plots/show_collection.py
new file mode 100644
index 00000000..cb88e12f
--- /dev/null
+++ b/doc/source/plots/show_collection.py
@@ -0,0 +1,28 @@
+import os
+
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid import AxesGrid
+import numpy as np
+
+from scikits.image.io import MultiImage
+from scikits.image import data_dir
+
+
+fname = os.path.join(data_dir, 'multipage.tif')
+img = MultiImage(fname)
+
+fig = plt.figure()
+grid = AxesGrid(fig, 111,
+                nrows_ncols = (1, 2),
+                axes_pad = 0.1,
+                add_all=True,
+                label_mode = "L",
+                aspect=True)
+
+for i, frame in enumerate(img):
+    grid[i].imshow(frame, cmap=plt.cm.gray)
+    grid[i].set_xlabel('Frame %s'%i)
+    grid[i].set_xticks([])
+    grid[i].set_yticks([])
+
+plt.show()
diff --git a/scikits/image/io/collection.py b/scikits/image/io/collection.py
index 3001dd46..399c3a70 100644
--- a/scikits/image/io/collection.py
+++ b/scikits/image/io/collection.py
@@ -57,9 +57,13 @@ class MultiImage(object):
     ...     print frame.shape
     (15, 10)
     (15, 10)
+
+    The two frames in this image can be shown with matplotlib:
+
+    .. plot:: ../plots/show_collection.py
     """
     def __init__(self, filename, conserve_memory=True, dtype=None):
-        """Load a multi-img"""
+        """Load a multi-img."""
         self._filename = filename
         self._conserve_memory = conserve_memory
         self._dtype = dtype