update documentation

Author: oesteban

doc/users/interface_tutorial.rst

@@ -10,7 +10,7 @@ Specifying input settings
 The nipype interface modules provide a Python interface to external
 packages like FSL_ and SPM_.  Within the module are a series of Python
 classes which wrap specific package functionality.  For example, in
-the fsl module, the class :class:`nipype.interfaces.fsl.Bet` wraps the
+the fsl module, the class :class:`nipype.interfaces.fsl.BET` wraps the
 ``bet`` command-line tool.  Using the command-line tool, one would
 specify input settings using flags like ``-o``, ``-m``, ``-f <f>``, etc...
 However, in nipype, options are assigned to Python attributes and can
@@ -81,6 +81,69 @@ In this case, ``mybet.inputs.frac`` will contain the value ``0.7`` regardless
 the value that could be stored in the ``bet-settings.json`` file.
 
 
+Controlling the standard output and error
+-----------------------------------------
+
+It is very likely that the software wrapped within the interface writes
+to the standard output or the standard error of the terminal.
+Interfaces provide a means to access and retrieve these outputs, by
+using the ``terminal_output`` attribute: ::
+
+  import nipype.interfaces.fsl as fsl
+  mybet = fsl.BET(from_file='bet-settings.json')
+  mybet.terminal_output = 'file_split'
+
+In the example, the ``terminal_output = 'file_split'`` will redirect the
+standard output and the standard error to split files (called
+``stdout.nipype`` and ``stderr.nipype`` respectively).
+The possible values for ``terminal_output`` are:
+
+*file*
+    Redirects both standard output and standard error to the same file
+    called ``output.nipype``.
+    Messages from both streams will be overlapped as they arrive to
+    the file.
+
+*file_split*
+    Redirects the output streams separately, to ``stdout.nipype``
+    and ``stderr.nipype`` respectively, as described in the example.
+
+*file_stdout*
+    Only the standard output will be redirected to ``stdout.nipype``
+    and the standard error will be discarded.
+
+*file_stderr*
+    Only the standard error will be redirected to ``stderr.nipype``
+    and the standard output will be discarded.
+
+*stream*
+    Both output streams are redirected to the current logger printing
+    their messages interleaved and immediately to the terminal.
+
+*allatonce*
+    Both output streams will be forwarded to a buffer and stored
+    separately in the `runtime` object that the `run()` method returns.
+    No files are written nor streams printed out to terminal.
+
+*none*
+    Both outputs are discarded
+
+In all cases, except for the ``'none'`` setting of ``terminal_output``,
+the ``run()`` method will return a "runtime" object that will contain
+the streams in the corresponding properties (``runtime.stdout``
+for the standard output, ``runtime.stderr`` for the standard error, and
+``runtime.merged`` for both when streams are mixed, eg. when using the
+*file* option). ::
+
+  import nipype.interfaces.fsl as fsl
+  mybet = fsl.BET(from_file='bet-settings.json')
+  mybet.terminal_output = 'file_split'
+  ...
+  result = mybet.run()
+  result.runtime.stdout
+  ' ... captured standard output ...'
+
+
 Getting Help
 ------------
 

doc/users/saving_workflows.rst

@@ -82,20 +82,20 @@ This will create a file "outputtestsave.py" with the following content:
 	bet2.inputs.environ = {'FSLOUTPUTTYPE': 'NIFTI_GZ'}
 	bet2.inputs.ignore_exception = False
 	bet2.inputs.output_type = 'NIFTI_GZ'
-	bet2.inputs.terminal_output = 'stream'
+	bet2.terminal_output = 'stream'
 	# Node: testsave.bet
 	bet = Node(BET(), name="bet")
 	bet.iterables = ('frac', [0.3, 0.4])
 	bet.inputs.environ = {'FSLOUTPUTTYPE': 'NIFTI_GZ'}
 	bet.inputs.ignore_exception = False
 	bet.inputs.output_type = 'NIFTI_GZ'
-	bet.inputs.terminal_output = 'stream'
+	bet.terminal_output = 'stream'
 	# Node: testsave.maths
 	maths = Node(ImageMaths(), name="maths")
 	maths.inputs.environ = {'FSLOUTPUTTYPE': 'NIFTI_GZ'}
 	maths.inputs.ignore_exception = False
 	maths.inputs.output_type = 'NIFTI_GZ'
-	maths.inputs.terminal_output = 'stream'
+	maths.terminal_output = 'stream'
 	testsave.connect(bet2, ('mask_file', func), maths, "in_file2")
 	testsave.connect(bet, "mask_file", maths, "in_file")
 	testsave.connect(testfunc, "output", maths, "op_string")