diff --git a/doc/examples/color_exposure/plot_equalize.py b/doc/examples/color_exposure/plot_equalize.py
index 079b8b6d..4b520897 100644
--- a/doc/examples/color_exposure/plot_equalize.py
+++ b/doc/examples/color_exposure/plot_equalize.py
@@ -72,12 +72,12 @@ img_adapteq = exposure.equalize_adapthist(img, clip_limit=0.03)
 
 # Display results
 fig = plt.figure(figsize=(8, 5))
-axes = np.zeros((2,4), dtype=np.object)
-axes[0,0] = fig.add_subplot(2, 4, 1)
-for i in range(1,4):
-    axes[0,i] = fig.add_subplot(2, 4, 1+i, sharex=axes[0,0], sharey=axes[0,0])
-for i in range(0,4):
-    axes[1,i] = fig.add_subplot(2, 4, 5+i)
+axes = np.zeros((2, 4), dtype=np.object)
+axes[0, 0] = fig.add_subplot(2, 4, 1)
+for i in range(1, 4):
+    axes[0, i] = fig.add_subplot(2, 4, 1+i, sharex=axes[0,0], sharey=axes[0,0])
+for i in range(0, 4):
+    axes[1, i] = fig.add_subplot(2, 4, 5+i)
 
 ax_img, ax_hist, ax_cdf = plot_img_and_hist(img, axes[:, 0])
 ax_img.set_title('Low contrast image')
diff --git a/doc/examples/color_exposure/plot_ihc_color_separation.py b/doc/examples/color_exposure/plot_ihc_color_separation.py
index db5343fc..b8f579d6 100644
--- a/doc/examples/color_exposure/plot_ihc_color_separation.py
+++ b/doc/examples/color_exposure/plot_ihc_color_separation.py
@@ -60,7 +60,6 @@ h = rescale_intensity(ihc_hed[:, :, 0], out_range=(0, 1))
 d = rescale_intensity(ihc_hed[:, :, 2], out_range=(0, 1))
 zdh = np.dstack((np.zeros_like(h), d, h))
 
-#fig, ax = plt.subplots()
 fig = plt.figure()
 ax = plt.subplot(1, 1, 1, sharex=ax0, sharey=ax0, adjustable='box-forced')
 ax.imshow(zdh)
diff --git a/doc/examples/features_detection/plot_gabors_from_astronaut.py b/doc/examples/features_detection/plot_gabors_from_astronaut.py
index a8cb50c2..8523d225 100644
--- a/doc/examples/features_detection/plot_gabors_from_astronaut.py
+++ b/doc/examples/features_detection/plot_gabors_from_astronaut.py
@@ -3,7 +3,7 @@
 Gabors / Primary Visual Cortex "Simple Cells" from an Image
 ============================================================
 
-How to build a (bio-plausible) "sparse" dictionary (or 'codebook', or
+How to build a (bio-plausible) *sparse* dictionary (or 'codebook', or
 'filterbank') for e.g. image classification without any fancy math and
 with just standard python scientific libraries?
 
diff --git a/doc/examples/features_detection/plot_holes_and_peaks.py b/doc/examples/features_detection/plot_holes_and_peaks.py
index 690a79f6..53a75f6f 100644
--- a/doc/examples/features_detection/plot_holes_and_peaks.py
+++ b/doc/examples/features_detection/plot_holes_and_peaks.py
@@ -3,11 +3,10 @@
 Filling holes and finding peaks
 ===============================
 
-In this example, we fill holes (i.e. isolated, dark spots) in an image using
-morphological reconstruction by erosion. Erosion expands the minimal values of
-the seed image until it encounters a mask image. Thus, the seed image and mask
-image represent the maximum and minimum possible values of the reconstructed
-image.
+We fill holes (i.e. isolated, dark spots) in an image using morphological
+reconstruction by erosion. Erosion expands the minimal values of the seed image
+until it encounters a mask image. Thus, the seed image and mask image represent
+the maximum and minimum possible values of the reconstructed image.
 
 We start with an image containing both peaks and holes:
 
@@ -21,14 +20,6 @@ image = data.moon()
 # Rescale image intensity so that we can see dim features.
 image = rescale_intensity(image, in_range=(50, 200))
 
-fig,ax = plt.subplots(2, 2, figsize=(5, 4), sharex=True, sharey=True, subplot_kw={'adjustable':'box-forced'})
-ax = ax.ravel()
-
-
-ax[0].imshow(image)
-ax[0].set_title('Original image')
-ax[0].axis('off')
-
 ######################################################################
 # Now we need to create the seed image, where the minima represent the
 # starting points for erosion.  To fill holes, we initialize the seed image
@@ -46,21 +37,12 @@ mask = image
 
 filled = reconstruction(seed, mask, method='erosion')
 
-ax[1].imshow(filled)
-ax[1].set_title('after filling holes')
-ax[1].axis('off')
-
 ######################################################################
 # As shown above, eroding inward from the edges removes holes, since (by
 # definition) holes are surrounded by pixels of brighter value. Finally, we
 # can isolate the dark regions by subtracting the reconstructed image from
 # the original image.
-
-ax[2].imshow(image-filled)
-ax[2].set_title('holes')
-ax[2].axis('off')
-
-######################################################################
+#
 # Alternatively, we can find bright spots in an image using morphological
 # reconstruction by dilation. Dilation is the inverse of erosion and expands
 # the *maximal* values of the seed image until it encounters a mask image.
@@ -72,7 +54,23 @@ seed = np.copy(image)
 seed[1:-1, 1:-1] = image.min()
 rec = reconstruction(seed, mask, method='dilation')
 
-ax[3].imshow(image-rec)
+fig, ax = plt.subplots(2, 2, figsize=(5, 4), sharex=True, sharey=True,
+                       subplot_kw={'adjustable': 'box-forced'})
+ax = ax.ravel()
+
+ax[0].imshow(image, cmap='gray')
+ax[0].set_title('Original image')
+ax[0].axis('off')
+
+ax[1].imshow(filled, cmap='gray')
+ax[1].set_title('after filling holes')
+ax[1].axis('off')
+
+ax[2].imshow(image-filled, cmap='gray')
+ax[2].set_title('holes')
+ax[2].axis('off')
+
+ax[3].imshow(image-rec, cmap='gray')
 ax[3].set_title('peaks')
 ax[3].axis('off')
 plt.show()
diff --git a/doc/examples/xx_applications/plot_morphology.py b/doc/examples/xx_applications/plot_morphology.py
index 9b4a12f5..6c94606f 100644
--- a/doc/examples/xx_applications/plot_morphology.py
+++ b/doc/examples/xx_applications/plot_morphology.py
@@ -12,19 +12,12 @@ neighborhood around a pixel.
 In this document we outline the following basic morphological operations:
 
 1. Erosion
-
 2. Dilation
-
 3. Opening
-
 4. Closing
-
 5. White Tophat
-
 6. Black Tophat
-
 7. Skeletonize
-
 8. Convex Hull
 
 
@@ -46,6 +39,7 @@ ax.imshow(orig_phantom, cmap=plt.cm.gray)
 ######################################################################
 # Let's also define a convenience function for plotting comparisons:
 
+
 def plot_comparison(original, filtered, filter_name):
 
     fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(8, 4), sharex=True,
@@ -188,9 +182,9 @@ plot_comparison(phantom, b_tophat, 'black tophat')
 #
 # 1. Erosion <-> Dilation
 #
-# 2. Opening <-> Closing
+# 2. Opening <-> Closing
 #
-# 3. White tophat <-> Black tophat
+# 3. White tophat <-> Black tophat
 #
 #Skeletonize
 #===========
diff --git a/doc/examples/xx_applications/plot_rank_filters.py b/doc/examples/xx_applications/plot_rank_filters.py
index 1d27deef..3d7fa692 100644
--- a/doc/examples/xx_applications/plot_rank_filters.py
+++ b/doc/examples/xx_applications/plot_rank_filters.py
@@ -467,7 +467,7 @@ for ax in ax.ravel():
 ######################################################################
 #
 # Feature extraction
-# ===================
+# ===================
 #
 # Local histograms can be exploited to compute local entropy, which is
 # related to the local image complexity. Entropy is computed using base 2
diff --git a/doc/ext/sphinx_gallery/LICENSE b/doc/ext/sphinx_gallery/LICENSE
new file mode 100644
index 00000000..1ad8acd4
--- /dev/null
+++ b/doc/ext/sphinx_gallery/LICENSE
@@ -0,0 +1,27 @@
+Copyright (c) 2015, Óscar Nájera
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of sphinx-gallery nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/doc/ext/sphinx_gallery/README.txt b/doc/ext/sphinx_gallery/README.txt
new file mode 100644
index 00000000..a9cd77a7
--- /dev/null
+++ b/doc/ext/sphinx_gallery/README.txt
@@ -0,0 +1,6 @@
+This directory was taken from
+https://github.com/sphinx-gallery/sphinx-gallery
+
+Files should not diverge from the original sphinx-gallery project, and
+any modifications should be submitted as pull requests to sphinx-gallery
+(with some exceptions such as CSS tweaking).
diff --git a/doc/ext/sphinx_gallery/_static/gallery.css b/doc/ext/sphinx_gallery/_static/gallery.css
index dd599b40..e8b6c7de 100644
--- a/doc/ext/sphinx_gallery/_static/gallery.css
+++ b/doc/ext/sphinx_gallery/_static/gallery.css
@@ -1,8 +1,8 @@
 /*
-Sphinx-Gallery is has compatible CSS to fix default sphinx themes
+Sphinx-Gallery has compatible CSS to fix default sphinx themes
 Tested for Sphinx 1.3.1 for all themes: default, alabaster, sphinxdoc,
 scrolls, agogo, traditional, nature, haiku, pyramid
-Tested for Read the docs theme 0.1.7 */
+Tested for Read the Docs theme 0.1.7 */
 .sphx-glr-thumbcontainer {
   background: #fff;
   border: solid #fff 1px;
@@ -12,7 +12,7 @@ Tested for Read the docs theme 0.1.7 */
   box-shadow: none;
   float: left;
   margin: 5px;
-  min-height: 230px;
+  min-height: 240px;
   padding-top: 5px;
   position: relative;
 }
@@ -40,12 +40,12 @@ thumbnail with its default link Background color */
 }
 .sphx-glr-thumbcontainer .figure {
   margin: 10px;
-  width: 160px;
+  width: 200px;
 }
 .sphx-glr-thumbcontainer img {
   display: inline;
-  max-height: 160px;
-  width: 160px;
+  max-height: 200px;
+  width: 200px;
 }
 .sphx-glr-thumbcontainer[tooltip]:hover:after {
   background: rgba(0, 0, 0, 0.8);
@@ -58,7 +58,7 @@ thumbnail with its default link Background color */
   padding: 5px 15px;
   position: absolute;
   z-index: 98;
-  width: 220px;
+  width: 240px;
   bottom: 52%;
 }
 .sphx-glr-thumbcontainer[tooltip]:hover:before {
@@ -125,3 +125,13 @@ ul.sphx-glr-horizontal li {
 ul.sphx-glr-horizontal img {
   height: auto !important;
 }
+
+p.sphx-glr-signature a.reference.external {
+  background-color: #EBECED;
+  -moz-border-radius: 5px;
+  -webkit-border-radius: 5px;
+  border-radius: 5px;
+  padding: 3px;
+  position: absolute;
+  right: 15px;
+}
diff --git a/doc/ext/sphinx_gallery/docs_resolv.py b/doc/ext/sphinx_gallery/docs_resolv.py
index 5e977111..1843ebdb 100644
--- a/doc/ext/sphinx_gallery/docs_resolv.py
+++ b/doc/ext/sphinx_gallery/docs_resolv.py
@@ -58,11 +58,7 @@ def get_data(url, gallery_dir):
     if sys.version_info[0] == 2 and isinstance(url, unicode):
         url = url.encode('utf-8')
 
-    cwd = os.getcwd()
-    if 'source' in cwd:
-        cached_file = os.path.join(gallery_dir, 'searchindex')
-    else:
-        cached_file = os.path.join('source', gallery_dir, 'searchindex')
+    cached_file = os.path.join(gallery_dir, 'searchindex')
     search_index = shelve.open(cached_file)
     if url in search_index:
         data = search_index[url]
@@ -321,6 +317,8 @@ class SphinxDocLinkResolver(object):
 
 def _embed_code_links(app, gallery_conf, gallery_dir):
     # Add resolvers for the packages for which we want to show links
+    working_dir = os.getcwd()
+    os.chdir(app.builder.srcdir)
     doc_resolvers = {}
     for this_module, url in gallery_conf['reference_url'].items():
         try:
@@ -344,8 +342,6 @@ def _embed_code_links(app, gallery_conf, gallery_dir):
                   "Error:\n".format(this_module))
             print(e.args)
 
-    working_dir = os.getcwd()
-    os.chdir(app.builder.srcdir)
     html_gallery_dir = os.path.abspath(os.path.join(app.builder.outdir,
                                                     gallery_dir))
     # patterns for replacement
diff --git a/doc/ext/sphinx_gallery/notebook.py b/doc/ext/sphinx_gallery/notebook.py
index c0ee5cd8..121e945a 100644
--- a/doc/ext/sphinx_gallery/notebook.py
+++ b/doc/ext/sphinx_gallery/notebook.py
@@ -4,7 +4,7 @@ r"""
 Parser for Jupyter notebooks
 ============================
 
-Class that holds the Ipython notebook information
+Class that holds the Jupyter notebook information
 
 """
 # Author: Óscar Nájera
@@ -48,7 +48,7 @@ def ipy_notebook_skeleton():
 
 def rst2md(text):
     """Converts the RST text from the examples docstrigs and comments
-    into markdown text for the IPython notebooks"""
+    into markdown text for the Jupyter notebooks"""
 
     top_heading = re.compile(r'^=+$\s^([\w\s-]+)^=+$', flags=re.M)
     text = re.sub(top_heading, r'# \1', text)
@@ -64,7 +64,7 @@ def rst2md(text):
 
 
 class Notebook(object):
-    """Ipython notebook object
+    """Jupyter notebook object
 
     Constructs the file cell-by-cell and writes it at the end"""
 
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 10d46de7..b460a23b 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -31,7 +31,6 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.imgmath',
               'numpydoc',
               'sphinx.ext.autosummary',
-              #'plot2rst',
               'sphinx.ext.intersphinx',
               'sphinx.ext.linkcode',
               'sphinx_gallery.gen_gallery'
diff --git a/doc/source/user_guide/numpy_images.rst b/doc/source/user_guide/numpy_images.rst
index 5b360494..13727161 100644
--- a/doc/source/user_guide/numpy_images.rst
+++ b/doc/source/user_guide/numpy_images.rst
@@ -81,7 +81,7 @@ disk: ::
     ...                    (nrows / 2)**2)
     >>> camera[outer_disk_mask] = 0
 
-.. image:: ../../_images/sphx_glr_plot_camera_numpy_001.png
+.. image:: ../auto_examples/numpy_operations/images/sphx_glr_plot_camera_numpy_001.png
     :width: 45%
     :target: ../auto_examples/numpy_operations/plot_camera_numpy.html
 
diff --git a/doc/source/user_guide/transforming_image_data.rst b/doc/source/user_guide/transforming_image_data.rst
index d9439888..79c6e03a 100644
--- a/doc/source/user_guide/transforming_image_data.rst
+++ b/doc/source/user_guide/transforming_image_data.rst
@@ -78,7 +78,7 @@ using an array of labels to encode the regions to be represented with the
 same color. 
 
 
-.. image:: ../../_images/sphx_glr_plot_join_segmentations_001.png
+.. image:: ../auto_examples/segmentation/images/sphx_glr_plot_join_segmentations_001.png
    :target: ../auto_examples/segmentation/plot_join_segmentations.html
    :align: center
    :width: 80%
@@ -159,7 +159,7 @@ image with :func:`equalize_adapthist`, in order to correct for exposure
 gradients across the image. See the example
 :ref:`sphx_glr_auto_examples_color_exposure_plot_equalize.py`.
 
-.. image:: ../../_images/sphx_glr_plot_equalize_001.png
+.. image:: ../auto_examples/color_exposure/images/sphx_glr_plot_equalize_001.png
    :target: ../auto_examples/color_exposure/plot_equalize.html
    :align: center
    :width: 90%
diff --git a/doc/source/user_guide/tutorial_segmentation.rst b/doc/source/user_guide/tutorial_segmentation.rst
index 522b7e2d..5ff5146c 100644
--- a/doc/source/user_guide/tutorial_segmentation.rst
+++ b/doc/source/user_guide/tutorial_segmentation.rst
@@ -11,7 +11,7 @@ the coins cannot be done directly from the histogram of grey values,
 because the background shares enough grey levels with the coins that a
 thresholding segmentation is not sufficient.
 
-.. image:: ../../_images/sphx_glr_plot_coins_segmentation_001.png
+.. image:: ../auto_examples/xx_applications/images/sphx_glr_plot_coins_segmentation_001.png
    :target: ../auto_examples/xx_applications/plot_coins_segmentation.html
    :align: center
 
@@ -26,7 +26,7 @@ Simply thresholding the image leads either to missing significant parts
 of the coins, or to merging parts of the background with the
 coins. This is due to the inhomogeneous lighting of the image. 
 
-.. image:: ../../_images/sphx_glr_plot_coins_segmentation_002.png
+.. image:: ../auto_examples/xx_applications/images/sphx_glr_plot_coins_segmentation_002.png
    :target: ../auto_examples/xx_applications/plot_coins_segmentation.html
    :align: center
 
@@ -53,7 +53,7 @@ boundary of the coins, or inside the coins.
     >>> from scipy import ndimage as ndi
     >>> fill_coins = ndi.binary_fill_holes(edges)
 
-.. image:: ../../_images/sphx_glr_plot_coins_segmentation_003.png
+.. image:: ../auto_examples/xx_applications/images/sphx_glr_plot_coins_segmentation_003.png
    :target: ../auto_examples/xx_applications/plot_coins_segmentation.html
    :align: center
 
@@ -62,7 +62,7 @@ we fill the inner part of the coins using the
 ``ndi.binary_fill_holes`` function, which uses mathematical morphology
 to fill the holes.
 
-.. image:: ../../_images/sphx_glr_plot_coins_segmentation_004.png
+.. image:: ../auto_examples/xx_applications/images/sphx_glr_plot_coins_segmentation_004.png
    :target: ../auto_examples/xx_applications/plot_coins_segmentation.html
    :align: center
 
@@ -83,7 +83,7 @@ has not been segmented correctly at all. The reason is that the contour
 that we got from the Canny detector was not completely closed, therefore
 the filling function did not fill the inner part of the coin. 
 
-.. image:: ../../_images/sphx_glr_plot_coins_segmentation_005.png
+.. image:: ../auto_examples/xx_applications/images/sphx_glr_plot_coins_segmentation_005.png
    :target: ../auto_examples/xx_applications/plot_coins_segmentation.html
    :align: center
 
@@ -128,7 +128,7 @@ separate the coins from the background.
 
 and here is the corresponding 2-D plot:
 
-.. image:: ../../_images/sphx_glr_plot_coins_segmentation_006.png
+.. image:: ../auto_examples/xx_applications/images/sphx_glr_plot_coins_segmentation_006.png
    :target: ../auto_examples/xx_applications/plot_coins_segmentation.html
    :align: center
 
@@ -139,7 +139,7 @@ extreme parts of the histogram of grey values::
     >>> markers[coins < 30] = 1
     >>> markers[coins > 150] = 2
 
-.. image:: ../../_images/sphx_glr_plot_coins_segmentation_007.png
+.. image:: ../auto_examples/xx_applications/images/sphx_glr_plot_coins_segmentation_007.png
    :target: ../auto_examples/xx_applications/plot_coins_segmentation.html
    :align: center
 
@@ -148,7 +148,7 @@ Let us now compute the watershed transform::
     >>> from skimage.morphology import watershed
     >>> segmentation = watershed(elevation_map, markers)
 
-.. image:: ../../_images/sphx_glr_plot_coins_segmentation_008.png
+.. image:: ../auto_examples/xx_applications/images/sphx_glr_plot_coins_segmentation_008.png
    :target: ../auto_examples/xx_applications/plot_coins_segmentation.html
    :align: center
 
@@ -165,7 +165,7 @@ We can now label all the coins one by one using ``ndi.label``::
 
     >>> labeled_coins, _ = ndi.label(segmentation)
 
-.. image:: ../../_images/sphx_glr_plot_coins_segmentation_009.png
+.. image:: ../auto_examples/xx_applications/images/sphx_glr_plot_coins_segmentation_009.png
    :target: ../auto_examples/xx_applications/plot_coins_segmentation.html
    :align: center