[med-svn] [python-mne] 342/353: ENH : new sphinx extension for example gallery
Yaroslav Halchenko
debian at onerussian.com
Fri Nov 27 17:25:29 UTC 2015
This is an automated email from the git hooks/post-receive script.
yoh pushed a commit to tag 0.4
in repository python-mne.
commit 792952b31ab8c869cd99f7a2852ebf2ee0e71367
Author: Alexandre Gramfort <alexandre.gramfort at inria.fr>
Date: Sun Aug 5 14:17:31 2012 +0200
ENH : new sphinx extension for example gallery
---
doc/Makefile | 6 +-
doc/source/_images/mne_helmet.png | Bin 0 -> 27218 bytes
doc/source/manual/list.rst | 5 +-
doc/sphinxext/gen_rst.py | 306 +++++++++++++++++----
examples/inverse/plot_mixed_norm_L21_inverse.py | 7 +-
examples/inverse/plot_read_inverse.py | 1 +
examples/inverse/plot_read_source_space.py | 1 +
examples/plot_read_bem_surfaces.py | 3 +-
examples/plot_read_forward.py | 1 +
.../plot_cluster_1samp_test_time_frequency.py | 4 +-
mne/viz.py | 25 +-
11 files changed, 284 insertions(+), 75 deletions(-)
diff --git a/doc/Makefile b/doc/Makefile
index e86b3f8..c3d4404 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -28,7 +28,11 @@ help:
clean:
-rm -rf build/*
- -rm -rf sources/auto_examples
+ -rm -rf source/auto_examples
+ -rm -rf source/generated
+ -rm -rf *.stc
+ -rm -rf *.fif
+ -rm -rf *.nii.gz
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
diff --git a/doc/source/_images/mne_helmet.png b/doc/source/_images/mne_helmet.png
new file mode 100644
index 0000000..bb21246
Binary files /dev/null and b/doc/source/_images/mne_helmet.png differ
diff --git a/doc/source/manual/list.rst b/doc/source/manual/list.rst
index 402e79a..ee5f9aa 100644
--- a/doc/source/manual/list.rst
+++ b/doc/source/manual/list.rst
@@ -433,4 +433,7 @@ listed in :ref:`CIHDGFAA`.
| | values, see :ref:`BABBGJEA`. |
+-------------------------+--------------------------------------------+
-.. note:: :ref:`setup_martinos` contains information specific to the setup at the Martinos Center including instructions to access the Neuromag software.
+.. note::
+
+ Section :ref:`setup_martinos` contains information specific to the setup at
+ the Martinos Center including instructions to access the Neuromag software.
diff --git a/doc/sphinxext/gen_rst.py b/doc/sphinxext/gen_rst.py
index 669d52d..44fd9e8 100644
--- a/doc/sphinxext/gen_rst.py
+++ b/doc/sphinxext/gen_rst.py
@@ -1,5 +1,5 @@
"""
-Example generation
+Example generation modified from the scikit learn
Generate the rst files for the examples by iterating over the python
example files.
@@ -7,17 +7,40 @@ example files.
Files that generate images should start with 'plot'
"""
+from time import time
import os
import shutil
import traceback
-
-fileList = []
+import glob
+import sys
+from StringIO import StringIO
import matplotlib
matplotlib.use('Agg')
-import token, tokenize
+import token
+import tokenize
+
+MAX_NB_LINES_STDOUT = 20
+
+###############################################################################
+# A tee object to redict streams to multiple outputs
+
+class Tee(object):
+
+ def __init__(self, file1, file2):
+ self.file1 = file1
+ self.file2 = file2
+
+ def write(self, data):
+ self.file1.write(data)
+ self.file2.write(data)
+ def flush(self):
+ self.file1.flush()
+ self.file2.flush()
+
+###############################################################################
rst_template = """
.. _example_%(short_fname)s:
@@ -36,15 +59,38 @@ plot_rst_template = """
%(docstring)s
-.. image:: images/%(image_name)s
- :align: center
+%(image_list)s
+
+%(stdout)s
**Python source code:** :download:`%(fname)s <%(fname)s>`
.. literalinclude:: %(fname)s
:lines: %(end_row)s-
+
+**Total running time of the example:** %(time_elapsed) 4i seconds
"""
+# The following strings are used when we have several pictures: we use
+# an html div tag that our CSS uses to turn the lists into horizontal
+# lists.
+HLIST_HEADER = """
+.. rst-class:: horizontal
+
+"""
+
+HLIST_IMAGE_TEMPLATE = """
+ *
+
+ .. image:: images/%s
+ :scale: 47
+"""
+
+SINGLE_IMAGE = """
+.. image:: images/%s
+ :align: center
+"""
+
def extract_docstring(filename):
""" Extract a module-level docstring, if any
@@ -57,7 +103,7 @@ def extract_docstring(filename):
docstring = ''
first_par = ''
- tokens = tokenize.generate_tokens(lines.__iter__().next)
+ tokens = tokenize.generate_tokens(iter(lines).next)
for tok_type, tok_content, _, (erow, _), _ in tokens:
tok_type = token.tok_name[tok_type]
if tok_type in ('NEWLINE', 'COMMENT', 'NL', 'INDENT', 'DEDENT'):
@@ -67,11 +113,11 @@ def extract_docstring(filename):
# If the docstring is formatted with several paragraphs, extract
# the first one:
paragraphs = '\n'.join(line.rstrip()
- for line in docstring.split('\n')).split('\n\n')
+ for line in docstring.split('\n')).split('\n\n')
if len(paragraphs) > 0:
first_par = paragraphs[0]
break
- return docstring, first_par, erow+1+start_row
+ return docstring, first_par, erow + 1 + start_row
def generate_example_rst(app):
@@ -79,7 +125,7 @@ def generate_example_rst(app):
examples.
"""
root_dir = os.path.join(app.builder.srcdir, 'auto_examples')
- example_dir = os.path.abspath(app.builder.srcdir + '/../../' + 'examples')
+ example_dir = os.path.abspath(app.builder.srcdir + '/../../' + 'examples')
try:
plot_gallery = eval(app.builder.config.plot_gallery)
except TypeError:
@@ -91,8 +137,37 @@ def generate_example_rst(app):
# we create an index.rst with all examples
fhindex = file(os.path.join(root_dir, 'index.rst'), 'w')
+ #Note: The sidebar button has been removed from the examples page for now
+ # due to how it messes up the layout. Will be fixed at a later point
fhindex.write("""\
+.. raw:: html
+
+
+ <style type="text/css">
+
+ div#sidebarbutton {
+ display: none;
+ }
+
+ .figure {
+ float: left;
+ margin: 10px;
+ width: auto;
+ height: 200px;
+ width: 180px;
+ }
+
+ .figure img {
+ display: inline;
+ }
+
+ .figure .caption {
+ width: 170px;
+ text-align: center !important;
+ }
+ </style>
+
Examples
========
@@ -102,8 +177,6 @@ Examples
# better than nested.
generate_dir_rst('.', fhindex, example_dir, root_dir, plot_gallery)
for dir in sorted(os.listdir(example_dir)):
- if dir == '.svn':
- continue
if os.path.isdir(os.path.join(example_dir, dir)):
generate_dir_rst(dir, fhindex, example_dir, root_dir, plot_gallery)
fhindex.flush()
@@ -112,87 +185,219 @@ Examples
def generate_dir_rst(dir, fhindex, example_dir, root_dir, plot_gallery):
""" Generate the rst file for an example directory.
"""
- target_dir = os.path.join(root_dir, dir)
- src_dir = os.path.join(example_dir, dir)
+ if not dir == '.':
+ target_dir = os.path.join(root_dir, dir)
+ src_dir = os.path.join(example_dir, dir)
+ else:
+ target_dir = root_dir
+ src_dir = example_dir
if not os.path.exists(os.path.join(src_dir, 'README.txt')):
- print 80*'_'
+ print 80 * '_'
print ('Example directory %s does not have a README.txt file'
% src_dir)
print 'Skipping this directory'
- print 80*'_'
+ print 80 * '_'
return
fhindex.write("""
+
%s
-.. toctree::
""" % file(os.path.join(src_dir, 'README.txt')).read())
if not os.path.exists(target_dir):
os.makedirs(target_dir)
- for fname in sorted(os.listdir(src_dir)):
+
+ def sort_key(a):
+ # put last elements without a plot
+ if not a.startswith('plot') and a.endswith('.py'):
+ return 'zz' + a
+ return a
+ for fname in sorted(os.listdir(src_dir), key=sort_key):
if fname.endswith('py'):
generate_file_rst(fname, target_dir, src_dir, plot_gallery)
- fhindex.write(' %s\n' % (os.path.join(dir, fname[:-3])))
+ thumb = os.path.join(dir, 'images', 'thumb', fname[:-3] + '.png')
+ link_name = os.path.join(dir, fname).replace(os.path.sep, '_')
+ fhindex.write('.. figure:: %s\n' % thumb)
+ if link_name.startswith('._'):
+ link_name = link_name[2:]
+ if dir != '.':
+ fhindex.write(' :target: ./%s/%s.html\n\n' % (dir,
+ fname[:-3]))
+ else:
+ fhindex.write(' :target: ./%s.html\n\n' % link_name[:-3])
+ fhindex.write(""" :ref:`example_%s`
+
+.. toctree::
+ :hidden:
+
+ %s/%s
+
+""" % (link_name, dir, fname[:-3]))
+ fhindex.write("""
+.. raw:: html
+
+ <div style="clear: both"></div>
+ """) # clear at the end of the section
def generate_file_rst(fname, target_dir, src_dir, plot_gallery):
""" Generate the rst file for a given example.
"""
- image_name = fname[:-2] + 'png'
- global rst_template, plot_rst_template
+ base_image_name = os.path.splitext(fname)[0]
+ image_fname = '%s_%%s.png' % base_image_name
+
this_template = rst_template
last_dir = os.path.split(src_dir)[-1]
- # to avoid leading . in file names
- if last_dir == '.': last_dir = ''
- else: last_dir += '_'
- short_fname = last_dir + fname
+ # to avoid leading . in file names, and wrong names in links
+ if last_dir == '.' or last_dir == 'examples':
+ last_dir = ''
+ else:
+ last_dir += '_'
+ short_fname = last_dir + fname
src_file = os.path.join(src_dir, fname)
example_file = os.path.join(target_dir, fname)
shutil.copyfile(src_file, example_file)
+
+ # The following is a list containing all the figure names
+ figure_list = []
+
+ image_dir = os.path.join(target_dir, 'images')
+ thumb_dir = os.path.join(image_dir, 'thumb')
+ if not os.path.exists(image_dir):
+ os.makedirs(image_dir)
+ if not os.path.exists(thumb_dir):
+ os.makedirs(thumb_dir)
+ image_path = os.path.join(image_dir, image_fname)
+ stdout_path = os.path.join(image_dir,
+ 'stdout_%s.txt' % base_image_name)
+ time_path = os.path.join(image_dir,
+ 'time_%s.txt' % base_image_name)
+ thumb_file = os.path.join(thumb_dir, fname[:-3] + '.png')
+ time_elapsed = 0
if plot_gallery and fname.startswith('plot'):
# generate the plot as png image if file name
# starts with plot and if it is more recent than an
# existing image.
- if not os.path.exists(os.path.join(target_dir, 'images')):
- os.makedirs(os.path.join(target_dir, 'images'))
- image_file = os.path.join(target_dir, 'images', image_name)
- if (not os.path.exists(image_file) or
- os.stat(image_file).st_mtime <= os.stat(src_file).st_mtime):
+ first_image_file = image_path % 1
+ if os.path.exists(stdout_path):
+ stdout = open(stdout_path).read()
+ else:
+ stdout = ''
+ if os.path.exists(time_path):
+ time_elapsed = float(open(time_path).read())
+
+ if (not os.path.exists(first_image_file) or
+ os.stat(first_image_file).st_mtime <=
+ os.stat(src_file).st_mtime):
+ # We need to execute the code
print 'plotting %s' % fname
+ t0 = time()
import matplotlib.pyplot as plt
plt.close('all')
+
try:
+ from mayavi import mlab
+ except Exception, e:
from enthought.mayavi import mlab
- mlab.close(all=True)
- except:
- pass
+ mlab.close(all=True)
+ cwd = os.getcwd()
try:
- execfile(example_file, {'pl' : plt})
- facecolor = plt.gcf().get_facecolor() # hack to keep black bg
- if facecolor == (0.0, 0.0, 0.0, 1.0):
- plt.savefig(image_file, facecolor='black')
- else:
- plt.savefig(image_file)
-
- try:
- from enthought.mayavi import mlab
- e = mlab.get_engine()
- if len(e.scenes) > 0:
- mlab.savefig(image_file)
- except:
- pass
+ # First CD in the original example dir, so that any file
+ # created by the example get created in this directory
+ orig_stdout = sys.stdout
+ os.chdir(os.path.dirname(src_file))
+ my_buffer = StringIO()
+ my_stdout = Tee(sys.stdout, my_buffer)
+ sys.stdout = my_stdout
+ my_globals = {'pl': plt}
+ execfile(os.path.basename(src_file), my_globals)
+ time_elapsed = time() - t0
+ sys.stdout = orig_stdout
+ my_stdout = my_buffer.getvalue()
+ if '__doc__' in my_globals:
+ # The __doc__ is often printed in the example, we
+ # don't with to echo it
+ my_stdout = my_stdout.replace(
+ my_globals['__doc__'],
+ '')
+ my_stdout = my_stdout.strip()
+ if my_stdout:
+ output_lines = my_stdout.split('\n')
+ if len(output_lines) > MAX_NB_LINES_STDOUT:
+ output_lines = output_lines[:MAX_NB_LINES_STDOUT]
+ output_lines.append('...')
+ stdout = '**Script output**::\n\n %s\n\n' % (
+ '\n '.join(output_lines))
+ open(stdout_path, 'w').write(stdout)
+ open(time_path, 'w').write('%f' % time_elapsed)
+ os.chdir(cwd)
+
+ # In order to save every figure we have two solutions :
+ # * iterate from 1 to infinity and call plt.fignum_exists(n)
+ # (this requires the figures to be numbered
+ # incrementally: 1, 2, 3 and not 1, 2, 5)
+ # * iterate over [fig_mngr.num for fig_mngr in
+ # matplotlib._pylab_helpers.Gcf.get_all_fig_managers()]
+ last_fig_num = 0
+ for fig_num in (fig_mngr.num for fig_mngr in
+ matplotlib._pylab_helpers.Gcf.get_all_fig_managers()):
+ # Set the fig_num figure as the current figure as we can't
+ # save a figure that's not the current figure.
+ plt.figure(fig_num)
+ facecolor = plt.gcf().get_facecolor() # hack to keep black bg
+ if facecolor == (0.0, 0.0, 0.0, 1.0):
+ plt.savefig(image_path % fig_num, facecolor='black')
+ else:
+ plt.savefig(image_path % fig_num)
+ figure_list.append(image_fname % fig_num)
+ last_fig_num = fig_num
+
+ e = mlab.get_engine()
+ for scene in e.scenes:
+ last_fig_num += 1
+ mlab.savefig(image_path % last_fig_num)
+ figure_list.append(image_fname % last_fig_num)
+ mlab.close(scene)
except:
- print 80*'_'
+ print 80 * '_'
print '%s is not compiling:' % fname
traceback.print_exc()
- print 80*'_'
+ print 80 * '_'
+ finally:
+ os.chdir(cwd)
+ sys.stdout = orig_stdout
+
+ print " - time elapsed : %.2g sec" % time_elapsed
+ else:
+ figure_list = [f[len(image_dir):]
+ for f in glob.glob(image_path % '[1-9]')]
+ #for f in glob.glob(image_path % '*')]
+
+ # generate thumb file
this_template = plot_rst_template
+ from matplotlib import image
+ if os.path.exists(first_image_file):
+ image.thumbnail(first_image_file, thumb_file, 0.2)
+
+ if not os.path.exists(thumb_file):
+ # create something not to replace the thumbnail
+ shutil.copy('source/_images/mne_helmet.png', thumb_file)
docstring, short_desc, end_row = extract_docstring(example_file)
+ # Depending on whether we have one or more figures, we're using a
+ # horizontal list or a single rst call to 'image'.
+ if len(figure_list) == 1:
+ figure_name = figure_list[0]
+ image_list = SINGLE_IMAGE % figure_name.lstrip('/')
+ else:
+ image_list = HLIST_HEADER
+ for figure_name in figure_list:
+ image_list += HLIST_IMAGE_TEMPLATE % figure_name.lstrip('/')
+
f = open(os.path.join(target_dir, fname[:-2] + 'rst'), 'w')
f.write(this_template % locals())
f.flush()
@@ -222,6 +427,3 @@ def setup(app):
for filename in filelist:
if filename.endswith('png'):
os.remove(os.path.join(build_image_dir, filename))
- build_download_dir = 'build/html/_downloads'
- if os.path.exists(build_download_dir):
- shutil.rmtree(build_download_dir)
diff --git a/examples/inverse/plot_mixed_norm_L21_inverse.py b/examples/inverse/plot_mixed_norm_L21_inverse.py
index b2b2458..ea93942 100644
--- a/examples/inverse/plot_mixed_norm_L21_inverse.py
+++ b/examples/inverse/plot_mixed_norm_L21_inverse.py
@@ -40,7 +40,7 @@ forward = mne.read_forward_solution(fwd_fname, force_fixed=True,
cov = mne.cov.regularize(cov, evoked.info)
import pylab as pl
-pl.figure(-2)
+pl.figure()
ylim = dict(eeg=[-10, 10], grad=[-400, 400], mag=[-600, 600])
plot_evoked(evoked, ylim=ylim, proj=True)
@@ -61,11 +61,10 @@ stc, residual = mixed_norm(evoked, forward, cov, alpha, loose=loose,
debias=True, weights=stc_dspm, weights_min=8.,
return_residual=True)
-pl.figure(-3)
+pl.figure()
plot_evoked(residual, ylim=ylim, proj=True)
###############################################################################
# View in 2D and 3D ("glass" brain like 3D plot)
plot_sparse_source_estimates(forward['src'], stc, bgcolor=(1, 1, 1),
- opacity=0.1, fig_name="MxNE (cond %s)" % setno,
- fig_number=setno)
+ opacity=0.1, fig_name="MxNE (cond %s)" % setno)
diff --git a/examples/inverse/plot_read_inverse.py b/examples/inverse/plot_read_inverse.py
index d7b2843..9b6a3de 100644
--- a/examples/inverse/plot_read_inverse.py
+++ b/examples/inverse/plot_read_inverse.py
@@ -30,6 +30,7 @@ lh_faces = inv['src'][0]['use_tris']
rh_points = inv['src'][1]['rr']
rh_faces = inv['src'][1]['use_tris']
from enthought.mayavi import mlab
+mlab.figure(size=(600, 600), bgcolor=(0, 0, 0))
mlab.triangular_mesh(lh_points[:, 0], lh_points[:, 1], lh_points[:, 2],
lh_faces)
mlab.triangular_mesh(rh_points[:, 0], rh_points[:, 1], rh_points[:, 2],
diff --git a/examples/inverse/plot_read_source_space.py b/examples/inverse/plot_read_source_space.py
index 8b1df69..53baf59 100644
--- a/examples/inverse/plot_read_source_space.py
+++ b/examples/inverse/plot_read_source_space.py
@@ -26,6 +26,7 @@ lh_faces = src[0]['tris']
rh_points = src[1]['rr']
rh_faces = src[1]['tris']
from enthought.mayavi import mlab
+mlab.figure(size=(600, 600), bgcolor=(0, 0, 0))
mlab.triangular_mesh(lh_points[:, 0], lh_points[:, 1], lh_points[:, 2],
lh_faces)
mlab.triangular_mesh(rh_points[:, 0], rh_points[:, 1], rh_points[:, 2],
diff --git a/examples/plot_read_bem_surfaces.py b/examples/plot_read_bem_surfaces.py
index fc8cb47..a41ecef 100644
--- a/examples/plot_read_bem_surfaces.py
+++ b/examples/plot_read_bem_surfaces.py
@@ -21,7 +21,6 @@ print "Number of surfaces : %d" % len(surfaces)
###############################################################################
# Show result
-
head_col = (0.95, 0.83, 0.83) # light pink
skull_col = (0.91, 0.89, 0.67)
brain_col = (0.67, 0.89, 0.91) # light blue
@@ -29,7 +28,7 @@ colors = [head_col, skull_col, brain_col]
# 3D source space
from enthought.mayavi import mlab
-mlab.clf()
+mlab.figure(size=(600, 600), bgcolor=(0, 0, 0))
for c, surf in zip(colors, surfaces):
points = surf['rr']
faces = surf['tris']
diff --git a/examples/plot_read_forward.py b/examples/plot_read_forward.py
index faf1f30..2563d8f 100644
--- a/examples/plot_read_forward.py
+++ b/examples/plot_read_forward.py
@@ -36,6 +36,7 @@ lh_faces = fwd['src'][0]['use_tris']
rh_points = fwd['src'][1]['rr']
rh_faces = fwd['src'][1]['use_tris']
from enthought.mayavi import mlab
+mlab.figure(size=(600, 600), bgcolor=(0, 0, 0))
mlab.triangular_mesh(lh_points[:, 0], lh_points[:, 1], lh_points[:, 2],
lh_faces)
mlab.triangular_mesh(rh_points[:, 0], rh_points[:, 1], rh_points[:, 2],
diff --git a/examples/stats/plot_cluster_1samp_test_time_frequency.py b/examples/stats/plot_cluster_1samp_test_time_frequency.py
index 69349a1..13b05a2 100644
--- a/examples/stats/plot_cluster_1samp_test_time_frequency.py
+++ b/examples/stats/plot_cluster_1samp_test_time_frequency.py
@@ -35,8 +35,8 @@ from mne.datasets import sample
data_path = sample.data_path('..')
raw_fname = data_path + '/MEG/sample/sample_audvis_raw.fif'
event_id = 1
-tmin = -0.2
-tmax = 0.5
+tmin = -0.3
+tmax = 0.6
# Setup for reading the raw data
raw = fiff.Raw(raw_fname)
diff --git a/mne/viz.py b/mne/viz.py
index fd01c06..a5dd63a 100644
--- a/mne/viz.py
+++ b/mne/viz.py
@@ -203,7 +203,7 @@ def plot_sparse_source_estimates(src, stcs, colors=None, linewidth=2,
from matplotlib.colors import ColorConverter
color_converter = ColorConverter()
- f = mlab.figure(figure=fig_name, bgcolor=bgcolor, size=(800, 800))
+ f = mlab.figure(figure=fig_name, bgcolor=bgcolor, size=(600, 600))
mlab.clf()
f.scene.disable_render = True
surface = mlab.triangular_mesh(points[:, 0], points[:, 1], points[:, 2],
@@ -257,7 +257,6 @@ def plot_sparse_source_estimates(src, stcs, colors=None, linewidth=2,
if show:
pl.show()
- mlab.show()
surface.actor.property.backface_culling = True
surface.actor.property.shading = True
@@ -325,6 +324,17 @@ def plot_cov(cov, info, exclude=[], colorbar=True, proj=False, show_svd=True,
import pylab as pl
+ pl.figure(figsize=(2.5 * len(idx_names), 2.7))
+ for k, (idx, name, _, _) in enumerate(idx_names):
+ pl.subplot(1, len(idx_names), k + 1)
+ pl.imshow(C[idx][:, idx], interpolation="nearest")
+ pl.title(name)
+ pl.subplots_adjust(0.04, 0.0, 0.98, 0.94, 0.2, 0.26)
+ try:
+ pl.tight_layout() # XXX : recent pylab feature
+ except:
+ pass
+
if show_svd:
pl.figure()
for k, (idx, name, unit, scaling) in enumerate(idx_names):
@@ -339,17 +349,6 @@ def plot_cov(cov, info, exclude=[], colorbar=True, proj=False, show_svd=True,
except:
pass
- pl.figure(figsize=(2.5 * len(idx_names), 2.7))
- for k, (idx, name, _, _) in enumerate(idx_names):
- pl.subplot(1, len(idx_names), k + 1)
- pl.imshow(C[idx][:, idx], interpolation="nearest")
- pl.title(name)
- pl.subplots_adjust(0.04, 0.0, 0.98, 0.94, 0.2, 0.26)
- try:
- pl.tight_layout() # XXX : recent pylab feature
- except:
- pass
-
if show:
pl.show()
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/python-mne.git
More information about the debian-med-commit
mailing list