Mayavi support

.travis.yml

@@ -15,6 +15,8 @@ env:
         - DISTRIB="ubuntu" PYTHON_VERSION="2.7"
         # This environment tests the oldest supported anaconda env
         - DISTRIB="conda" PYTHON_VERSION="2.6"
+        # This environment tests is for mayavi
+        - DISTRIB="conda" PYTHON_VERSION="2.7"
         # This environment tests the newest supported anaconda env
         - DISTRIB="conda" PYTHON_VERSION="3.4"
 
@@ -29,9 +31,13 @@ before_install:
 
 install:
     - if [ "$DISTRIB" == "conda" ]; then
-         conda create --yes -n testenv python=$PYTHON_VERSION pip numpy
-         setuptools matplotlib pillow sphinx nose;
-         source activate testenv; fi
+        conda create --yes -n testenv python=$PYTHON_VERSION pip numpy
+        setuptools matplotlib pillow sphinx nose;
+        if [ "$PYTHON_VERSION" == "2.7" ]; then
+          conda install --yes --quiet mayavi;
+        fi;
+        source activate testenv;
+      fi;
     - pip install -r requirements.txt
     - python setup.py install
 

doc/Makefile

@@ -48,6 +48,7 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf auto_examples/
+	rm -rf auto_mayavi_examples/
 	rm -rf tutorials/
 	rm -rf generated/*
 	rm -rf modules/generated/*

doc/conf.py

@@ -274,12 +274,25 @@ def setup(app):
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
 
+
+try:
+    from mayavi import mlab
+    find_mayavi_figures = True
+    examples_dir = ['../examples', '../tutorials', '../mayavi_examples']
+    gallery_dir = ['auto_examples', 'tutorials', 'auto_mayavi_examples']
+except ImportError:
+    find_mayavi_figures = False
+    examples_dir = ['../examples', '../tutorials']
+    gallery_dir = ['auto_examples', 'tutorials']
+
+
 sphinxgallery_conf = {
     'doc_module': ('sphinxgallery', 'numpy'),
     'reference_url': {
         'sphinxgallery': None,
         'matplotlib': 'http://matplotlib.org',
         'numpy': 'http://docs.scipy.org/doc/numpy-1.9.1'},
-    'examples_dir'   : ['../examples', '../tutorials'],
-    'gallery_dir'    : ['auto_examples', 'tutorials'],
+    'examples_dir': examples_dir,
+    'gallery_dir': gallery_dir,
+    'find_mayavi_figures': find_mayavi_figures,
     }

doc/index.rst

@@ -22,6 +22,7 @@ Contents:
    reference
    auto_examples/index
    tutorials/index
+   auto_mayavi_examples/index
 
 Sphinx-Gallery Show: :ref:`examples-index`
 ''''''''''''''''''''''''''''''''''''''''''

mayavi_examples/README.txt

@@ -0,0 +1,12 @@
+.. _mayavi-examples-index:
+
+Gallery of Examples using Mayavi
+================================
+
+
+.. _general_mayavi_examples:
+
+Mayavi examples
+---------------
+
+Examples from the sphinx-gallery using Mayavi for embedding 3d plots.

mayavi_examples/plot_3d.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+"""
+====================================
+Plotting simple 3D graph with Mayavi
+====================================
+
+A simple example of the plot of a 3D graph with Mayavi
+in order to test the autonomy of the gallery.
+"""
+
+# Code source: Alex Gramfort
+# License: BSD 3 clause
+
+from mayavi import mlab
+
+mlab.test_plot3d()
+
+mlab.figure()
+mlab.test_contour3d()

sphinxgallery/docs_resolv.py

@@ -409,6 +409,8 @@ def embed_code_links(app, exception):
     """Embed hyperlinks to documentation into example code"""
     if exception is not None:
         return
+    if not app.builder.config.plot_gallery:
+        return  # no need to embed
     print('Embedding documentation hyperlinks in examples..')
 
     if app.builder.name == 'latex':

sphinxgallery/gen_rst.py

@@ -225,7 +225,7 @@ def _plots_are_current(src_file, image_file):
     return not needs_replot
 
 
-def save_figures(image_path, fig_count):
+def save_figures(image_path, fig_count, gallery_conf):
     """Save all open matplotlib figures of the example code-block
 
     Parameters
@@ -257,6 +257,22 @@ def save_figures(image_path, fig_count):
         current_fig = image_path.format(fig_count + fig_mngr.num)
         fig.savefig(current_fig, **kwargs)
         figure_list.append(current_fig)
+
+    if gallery_conf.get('find_mayavi_figures', False):
+        from mayavi import mlab
+        e = mlab.get_engine()
+        last_matplotlib_fig_num = len(figure_list)
+        total_fig_num = last_matplotlib_fig_num + len(e.scenes)
+        mayavi_fig_nums = range(last_matplotlib_fig_num, total_fig_num)
+
+        for scene, mayavi_fig_num in zip(e.scenes, mayavi_fig_nums):
+            current_fig = image_path.format(mayavi_fig_num)
+            mlab.savefig(current_fig, figure=scene)
+            # make sure the image is not too large
+            scale_image(current_fig, current_fig, 850, 999)
+            figure_list.append(current_fig)
+        mlab.close(all=True)
+
     return figure_list
 
 
@@ -339,7 +355,7 @@ def generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs):
     sorted_listdir = [fname for fname in sorted(os.listdir(src_dir))
                       if fname.endswith('py')]
     for fname in sorted_listdir:
-        generate_file_rst(fname, target_dir, src_dir)
+        generate_file_rst(fname, target_dir, src_dir, gallery_conf)
         new_fname = os.path.join(src_dir, fname)
         intro = extract_intro(new_fname)
         write_backreferences(seen_backrefs, gallery_conf,
@@ -361,7 +377,7 @@ def generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs):
 
 
 def execute_script(code_block, example_globals, image_path, fig_count,
-                   src_file):
+                   src_file, gallery_conf):
     """Executes the code block of the example file"""
     time_elapsed = 0
     stdout = ''
@@ -392,7 +408,7 @@ def execute_script(code_block, example_globals, image_path, fig_count,
         if my_stdout:
             stdout = CODE_OUTPUT.format(indent(my_stdout, ' ' * 4))
         os.chdir(cwd)
-        figure_list = save_figures(image_path, fig_count)
+        figure_list = save_figures(image_path, fig_count, gallery_conf)
 
         # Depending on whether we have one or more figures, we're using a
         # horizontal list or a single rst call to 'image'.
@@ -405,6 +421,7 @@ def execute_script(code_block, example_globals, image_path, fig_count,
                 image_list += HLIST_IMAGE_TEMPLATE % figure_name.lstrip('/')
 
     except Exception:
+        figure_list = []
         image_list = '%s is not compiling:' % src_file
         print(80 * '_')
         print(image_list)
@@ -420,7 +437,7 @@ def execute_script(code_block, example_globals, image_path, fig_count,
     return code_output, time_elapsed, fig_count + len(figure_list)
 
 
-def generate_file_rst(fname, target_dir, src_dir):
+def generate_file_rst(fname, target_dir, src_dir, gallery_conf):
     """ Generate the rst file for a given example."""
 
     src_file = os.path.join(src_dir, fname)
@@ -460,7 +477,8 @@ def generate_file_rst(fname, target_dir, src_dir):
                                                                example_globals,
                                                                image_path,
                                                                fig_count,
-                                                               src_file)
+                                                               src_file,
+                                                               gallery_conf)
 
                 time_elapsed += rtime