enh: refined example building so that one can download the code

Author: satra

doc/Makefile

@@ -26,7 +26,7 @@ help:
 	@echo "  sf_satra copy html files to sourceforge (satra only)"
 
 clean:
-	-rm -rf _build/* *~ api/generated documentation.zip
+	-rm -rf _build/* *~ api/generated users/examples documentation.zip
 
 htmlonly:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
@@ -45,25 +45,8 @@ html: examples2rst api htmlonly
 	stty sane
 
 examples2rst:
-	python ../tools/ex2rst \
-			--project Nipype \
-			--outdir $(CURDIR)/users/examples \
-			../examples/freesurfer_tutorial.py \
-			../examples/fsl_tutorial2.py \
-			../examples/fsl_feeds_tutorial.py \
-			../examples/fsl_resting_compcorr.py \
-			../examples/spm_tutorial.py \
-			../examples/spm_face_tutorial.py \
-			../examples/spm_auditory_tutorial.py \
-			../examples/fsl_dti_tutorial.py \
-			../examples/camino_dti_tutorial.py \
-			../examples/connectivity_tutorial.py \
-			../examples/dtk_dti_tutorial.py \
-			../examples/dtk_odf_tutorial.py \
-			../examples/spm_tutorial2.py \
-			../examples/spm_dartel_tutorial.py \
-			../examples/dartmouth_workshop_2010.py \
-			../examples/nipy_tutorial.py
+	mkdir -p users/examples
+	../tools/make_examples.py --no-exec
 	@echo "examples2rst finished."
 
 latex: api

doc/users/parallel_processing.rst

@@ -73,7 +73,7 @@ To prevent prevent parallel execution type::
     workflow.run(plugin='Linear')
 
 Using the pipeline engine with SGE/OGE/PBS
---------------------------------------
+------------------------------------------
 
 In order to use nipype with SGE_/OGE_ (not tested) or PBS_ you simply need to
 call::

examples/frontiers_paper/smoothing_comparison.py

@@ -1,3 +1,5 @@
+# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
+# vi: set ft=python sts=4 ts=4 sw=4 et:
 """
 =============================
 Smoothing comparison workflow

examples/frontiers_paper/workflow_from_scratch.py

@@ -1,3 +1,5 @@
+# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
+# vi: set ft=python sts=4 ts=4 sw=4 et:
 """
 =====================
 Workflow from scratch

examples/slicer_tutorial.py

@@ -2,7 +2,7 @@
 # vi: set ft=python sts=4 ts=4 sw=4 et:
 """
 Using slicer for analysis
-=======================
+=========================
 
 The slicer_tutorial.py
 
@@ -14,6 +14,7 @@
     python slicer_tutorial.py
 
 """
+
 raise RuntimeWarning, 'Slicer not fully implmented'
 from nipype.interfaces.slicer import SlicerCommandLine
 

examples/tbss_tutorial.py

@@ -1,22 +1,17 @@
 #!/usr/bin/env python
-"""Helper to automagically generate ReST versions of examples.
-
-The MIT License
-
- Copyright (c) 2006-2009 Michael Hanke
-               2007-2009 Yaroslav Halchenko
-
- Permission is hereby granted, free of charge, to any person obtaining a copy
- of this software and associated documentation files (the "Software"), to deal
- in the Software without restriction, including without limitation the rights
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- copies of the Software, and to permit persons to whom the Software is
- furnished to do so, subject to the following conditions:
-
- The above copyright notice and this permission notice shall be included in
- all copies or substantial portions of the Software.
-
-"""
+#
+# Note: this file is copied (possibly with minor modifications) from the
+# sources of the PyMVPA project - http://pymvpa.org.  It remains licensed as
+# the rest of PyMVPA (MIT license as of October 2010).
+#
+### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
+#
+#   See COPYING file distributed along with the PyMVPA package for the
+#   copyright and license terms.
+#
+### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
+
+"""Helper to automagically generate ReST versions of examples"""
 
 __docformat__ = 'restructuredtext'
 
@@ -28,6 +23,31 @@ import glob
 from optparse import OptionParser
 
 
+def auto_image(line):
+    """Automatically replace generic image markers with ones that have full
+    size (width/height) info, plus a :target: link to the original png, to be
+    used in the html docs.
+    """
+    img_re = re.compile(r'(\s*)\.\. image::\s*(.*)$')
+    m = img_re.match(line)
+    if m is None:
+        # Not an image declaration, leave the line alone and return unmodified
+        return line
+
+    # Match means it's an image spec, we rewrite it with extra tags
+    ini_space = m.group(1)
+    lines = [line,
+             ini_space + '   :width: 500\n',
+             #ini_space + '   :height: 350\n'
+             ]
+    fspec = m.group(2)
+    if fspec.endswith('.*'):
+        fspec = fspec.replace('.*', '.png')
+    fspec = fspec.replace('fig/', '../_images/')
+    lines.append(ini_space + ('   :target: %s\n' % fspec) )
+    lines.append('\n')
+    return ''.join(lines)
+
 def exfile2rst(filename):
     """Open a Python script and convert it into an ReST string.
     """
@@ -42,8 +62,6 @@ def exfile2rst(filename):
     indocs = False
     doc2code = False
     code2doc = False
-    interactiveblock = False
-    preserved_indent = False
     # an empty line found in the example enables the check for a potentially
     # indented docstring starting on the next line (as an attempt to exclude
     # function or class docstrings)
@@ -67,7 +85,6 @@ def exfile2rst(filename):
             cleanline = line[:line.find('#')].lstrip()
             indent_level = len(line) - len(cleanline) - 1
             cleanline = cleanline.rstrip()
-            interactiveblock = False
         else:
             cleanline = line[:line.find('#')].rstrip()
 
@@ -92,19 +109,16 @@ def exfile2rst(filename):
                     proc_line = cleanline[3:-3]
                 else:
                     # must be start of multiline block
-                    interactiveblock = False
                     indocs = True
                     code2doc = True
                     # rescue what is left on the line
                     proc_line = cleanline[3:] # strip """
-                first_codeline_in_block = False
             else:
                 # we are already in the docs
                 # handle doc end
                 if cleanline.endswith('"""') or cleanline.endswith("'''"):
                     indocs = False
                     doc2code = True
-                    preserved_indent = False
                     # rescue what is left on the line
                     proc_line = cleanline[:-3]
                     # reset the indentation
@@ -122,40 +136,18 @@ def exfile2rst(filename):
                 code2doc = False
                 s += '\n'
 
+            proc_line = auto_image(proc_line)
+            
             if proc_line:
                 s += proc_line.rstrip() + '\n'
 
         else:
-            # we are in a code block
-            if line.startswith("if cfg.getboolean('examples', 'interactive'"):
-                interactiveblock = True
-            elif not interactiveblock:
-                # we exclude the code that is used to disable the interactive
-                # plots.
-                if doc2code:
-                    doc2code = False
-                    first_codeline_in_block = True
-                    # the spaces at the end are crucial to get intentation of
-                    # indented code block -- otherwise sphinx removes common
-                    # whitespace
-                    s += '\n::\n'
-
-                # has to be code
-                leading_whitespace = len(line) > 2 \
-                                     and len(line) > len(line.lstrip())
-                line = line.rstrip()
-                # anything left?
-                if line:
-                    if first_codeline_in_block and leading_whitespace \
-                            and not preserved_indent:
-                        s += ' >>%s\n' % line
-                        preserved_indent = True
-                    else:
-                        s += '  %s\n' % line
-
-                    first_codeline_in_block = False
-                else:
-                    s += '\n'
+            if doc2code:
+                doc2code = False
+                s += '\n::\n'
+
+            # has to be code
+            s += '  %s' % line
 
     xfile.close()
 
@@ -179,15 +171,20 @@ def exfile2rstfile(filename, opts):
 
     # write converted ReST
     dfile.write(exfile2rst(filename))
-    
-    # add links
-    dfile.write('.. include:: ../../links_names.txt\n\n')
 
     if opts.sourceref:
         # write post example see also box
-        dfile.write("\n.. seealso::\n  The full source code of this example is "
-                    "included in the %s source distribution (`%s`).\n"
-                    % (opts.project, filename))
+        msg = """
+        
+.. admonition:: Example source code
+
+   You can download :download:`the full source code of this example <%s>`.
+   This same script is also included in the %s source distribution under the
+   :file:`examples` directory.
+
+"""    % (filename, opts.project)
+
+        dfile.write(msg)
 
     dfile.close()
 
@@ -215,7 +212,7 @@ the respective indentation is removed in the ReST output.
 
 The parser algorithm automatically excludes file headers and starts with the
 first (module-level) docstring instead.
-""" )
+""" ) #'
 
     # define options
     parser.add_option('--verbose', action='store_true', dest='verbose',
@@ -269,7 +266,7 @@ Name of the project that contains the examples. This name is used in the
         print('Ignoring duplicate parse targets.')
 
     if not os.path.exists(opts.outdir):
-        os.mkdir(opts.outdir)
+        os.mkdir(outdir)
 
     # finally process all examples
     for t in toparse: