Improve documentation around live data

docs/source/algorithms/LoadLiveData-v1.rst

@@ -10,14 +10,15 @@ Description
 -----------
 
 This algorithm is called on a regular interval by the
-:ref:`algm-MonitorLiveData` algorithm. and the whole process is started by the :ref:`algm-StartLiveData` algorithm.  **It should not be
-necessary to call LoadLiveData directly.**
+:ref:`algm-MonitorLiveData` algorithm. and the whole process is
+started by the :ref:`algm-StartLiveData` algorithm.  **It should not
+be necessary to call LoadLiveData directly.**
 
 .. figure:: /images/LoadLiveData_flow.png
    :alt: LoadLiveData_flow.png
 
    LoadLiveData\_flow.png
-   
+
 Data Processing
 ###############
 
@@ -32,55 +33,63 @@ Data Processing
 Processing with an Algorithm
 ############################
 
--  Specify the name of the algorithm in the *ProcessingAlgorithm*
+-  Specify the name of the algorithm in the ``ProcessingAlgorithm``
    property.
 
    -  This could be, e.g. a `Python Algorithm <Python Algorithm>`__
       written for this purpose.
-   -  The algorithm *must* have at least 2 properties: *InputWorkspace*
-      and *OutputWorkspace*.
+   -  The algorithm *must* have at least 2 properties: ``InputWorkspace``
+      and ``OutputWorkspace``.
    -  Any other properties are set from the string in
-      *ProcessingProperties*.
-   -  The algorithm is then run, and its OutputWorkspace is saved.
+      ``ProcessingProperties``.
+   -  The algorithm is then run, and its ``OutputWorkspace`` is saved.
 
 Processing with a Python Script
 ###############################
 
--  Specify a python script in the *ProcessingScript* property.
+The python script is run using :ref:`algm-RunPythonScript`. Please see
+its documentation for details of how the script is run.
+
+-  Specify a python script in the ``ProcessingScript`` property.
 
    -  This can have several lines.
    -  Two variables have special meaning:
 
-      -  *input* is the input workspace.
-      -  *output* is the name of the processed, output workspace.
+      -  ``input`` is a reference to the input workspace.
+      -  ``output`` is the name of the processed, output workspace.
 
    -  Otherwise, your script can contain any legal python code including
       calls to other Mantid algorithms.
    -  If you create temporary workspaces, you should delete them in the
       script.
 
+-  Specify a python script in the ``ProcessingScriptFilename`` property.
+
+   - Contents of the file have the exact same rules as specifying the ``ProcessingScript``
+
 Data Accumulation
 #################
 
--  The *AccumulationMethod* property specifies what to do with each
+-  The ``AccumulationMethod`` property specifies what to do with each
    chunk.
 
-   -  If you select 'Add', the chunks of processed data will be added
+   -  If you select ``Add``, the chunks of processed data will be added
       using :ref:`algm-Plus` or :ref:`algm-PlusMD`.
-   -  If you select 'Replace', then the output workspace will always be
+   -  If you select ``Replace``, then the output workspace will always be
       equal to the latest processed chunk.
-   -  If you select 'Append', then the spectra from each chunk will be
+   -  If you select ``Append``, then the spectra from each chunk will be
       appended to the output workspace.
 
 A Warning About Events
 ######################
 
-Beware! If you select *PreserveEvents* and your processing keeps the
-data as :ref:`EventWorkspaces <EventWorkspace>`, you may end up creating
-**very large** EventWorkspaces in long runs. Most plots require
-re-sorting the events, which is an operation that gets much slower as
-the list gets bigger (Order of N\*log(N)). This could cause Mantid to
-run very slowly or to crash due to lack of memory.
+Beware! If you select ``PreserveEvents=True`` and your processing
+keeps the data as :ref:`EventWorkspaces <EventWorkspace>`, you may end
+up creating **very large** EventWorkspaces in long runs. Most plots
+require re-sorting the events, which is an operation that gets much
+slower as the list gets bigger (Order of :math:`N * log(N)`). This
+could cause Mantid to run very slowly or to crash due to lack of
+memory.
 
 Post-Processing Step
 ####################
@@ -88,17 +97,19 @@ Post-Processing Step
 -  Optionally, you can specify some processing to perform *after*
    accumulation.
 
-   -  You then need to specify the *AccumulationWorkspace* property.
+   -  You then need to specify the ``AccumulationWorkspace`` property.
 
--  Using either the *PostProcessingAlgorithm* or the
-   *PostProcessingScript* (same way as above), the
-   *AccumulationWorkspace* is processed into the *OutputWorkspace*
+- Using either the ``PostProcessingAlgorithm``,
+   ``PostProcessingScript``, or ``PostProcessingScriptFilename`` (same
+   way as above), the ``AccumulationWorkspace`` is processed into the
+   ``OutputWorkspace``
 
 Usage
 -----
 
-LoadLiveData is not intended for usage directly, it is part of he process that is started using :ref:`algm-StartLiveData`.
-    
+LoadLiveData is not intended for usage directly, it is part of he
+process that is started using :ref:`algm-StartLiveData`.
+
 
 .. categories::
 

docs/source/algorithms/RunPythonScript-v1.rst

@@ -12,12 +12,17 @@ Description
 Algorithm that will run a snippet of python code. This is meant to be
 used by :ref:`algm-LoadLiveData` to perform some processing.
 
-The input & output workspaces can be accessed from the Python code using
-the variable names 'input' & 'output' respectively.
+The input & output workspaces can be accessed from the Python code
+using the variable names ``input`` and ``output`` respectively.
 
-Within your code "input" is an actual reference to the input workspace, while "output" is a string of the output workspace name.
+Within your code ``input`` is an actual reference to the input
+workspace, while ``output`` is a string of the output workspace name.
 You are expected to create the output workspace yourself.
 
+Because of boilerplate code added to the python script being run,
+stack-traces for errors will be five (5) lines greater than where the
+error occured in the supplied python code.
+
 Usage
 -----
 
@@ -26,14 +31,14 @@ Usage
 .. testcode:: exRunPythonScript
 
     ws = CreateSampleWorkspace("Histogram","Multiple Peaks")
-    
+
     script = """
     logger.notice('Logging from within the python script!')
     wsOut = Integration(input,OutputWorkspace=output)
     wsOut = SumSpectra(wsOut)
     """
 
-    RunPythonScript(script,ws,"wsOut")
+    RunPythonScript(InputWorkspace=ws,Code=script,OutputWorkspace="wsOut")
 
     wsOut = mtd["wsOut"]
     print "The workspace contained a total of %i counts" % wsOut.readY(0)[0]
@@ -44,6 +49,8 @@ Output:
 
     The workspace contained a total of 9599 counts
 
+The same script could be saved to a file and specified using the
+``Filename`` property instead of the ``Code`` property.
 
 .. categories::
 

docs/source/algorithms/StartLiveData-v1.rst

@@ -9,15 +9,16 @@
 Description
 -----------
 
-The StartLiveData algorithm launches a background job that monitors and
+The ``StartLiveData`` algorithm launches a background job that monitors and
 processes live data.
 
-The background algorithm started is
-:ref:`algm-MonitorLiveData`, which simply calls
-:ref:`algm-LoadLiveData` at a fixed interval.
+The background algorithm started is :ref:`algm-MonitorLiveData`, which
+simply calls :ref:`algm-LoadLiveData` at a fixed interval.
 
-For details on the way to specify the data processing steps, see:
-`LoadLiveData <LoadLiveData#Description>`__.
+.. note::
+
+   For details on the way to specify the data processing steps, see
+   `LoadLiveData <LoadLiveData#Description>`__.
 
 Live Plots
 ##########
@@ -46,15 +47,15 @@ Run Transition Behavior
 
 -  When the experimenter starts and stops a run, the Live Data Listener
    receives this as a signal.
--  The *RunTransitionBehavior* property specifies what to do at these
+-  The ``RunTransitionBehavior`` property specifies what to do at these
    run transitions.
 
-   -  Restart: the accumulated data (from the previous run if a run has
+   -  ``Restart``: the accumulated data (from the previous run if a run has
       just ended or from the time between runs a if a run has just
       started) is discarded as soon as the next chunk of data arrives.
-   -  Stop: live data monitoring ends. It will have to be restarted
+   -  ``Stop``: live data monitoring ends. It will have to be restarted
       manually.
-   -  Rename: the previous workspaces are renamed, and monitoring
+   -  ``Rename``: the previous workspaces are renamed, and monitoring
       continues with cleared ones. The run number, if found, is used to
       rename the old workspaces.
 
@@ -68,8 +69,8 @@ Multiple Live Data Sessions
 ###########################
 
 It is possible to have multiple live data sessions running at the same
-time. Simply call StartLiveData more than once, but make sure to specify
-unique names for the *OutputWorkspace*.
+time. Simply call ``StartLiveData`` more than once, but make sure to specify
+unique names for the ``OutputWorkspace``.
 
 Please note that you may be limited in how much simultaneous processing
 you can do by your available memory and CPUs.
@@ -160,7 +161,7 @@ Output:
     def captureLive():
         ConfigService.setFacility("TEST_LIVE")
 
-        # Start a Live data listener updating every second, 
+        # Start a Live data listener updating every second,
         # that replaces the results each time with those of the last second.
         # Load only spectra 2,4, and 6 from periods 1 and 3
         StartLiveData(Instrument='ISIS_Histogram', OutputWorkspace='wsOut', UpdateEvery=1,

docs/source/release/v3.8.0/framework.rst

@@ -83,6 +83,8 @@ Improved
 
 - :ref:`FFT <algm-FFT>` deals correctly with histogram input data. Internally, it converts to point data, and the output is always a point data workspace. (It can be converted to histogram data using :ref:`ConvertToHistogram <algm-ConvertToHistogram>` if required).
 
+-  :ref:`StartLiveDataClearCache <algm-StartLiveData>` has additional properties for specifying scripts to run for processing and post-processing.
+
 Deprecated
 ##########