Updated docs regarding the functionality of redirecting stdout/stderr

Author: mikicz

README.rst

@@ -101,7 +101,8 @@ To call the function using Arca, the following example would do so:
 
 The code would print ``Hello World!``.
 ``result`` would be a ``arca.Result`` instance. ``arca.Result`` has three attributes,
-``output`` with the return value of the function call, ``stdout`` and ``stderr`` contain things printed to the standard outputs.
+``output`` with the return value of the function call, ``stdout`` and ``stderr`` contain things printed to the standard outputs
+(see the section about `Result <http://arca.readthedocs.io/en/latest/tasks.html#result>`_ for more info about the capture of the standard outputs).
 If the task fails, ``arca.exceptions.BuildError`` would be raised.
 
 By default, the `Current Environment Backend <https://arca.readthedocs.io/en/latest/backends.html#current-environment>`_ is used to run tasks,

docs/quickstart.rst

@@ -42,7 +42,8 @@ To call the function using Arca, the following example would do so:
 The code would print ``Hello World!``.
 
 ``result`` would be a :class:`Result <arca.Result>` instance. :class:`Result <arca.Result>` has three attributes,
-``output`` with the return value of the function call, ``stdout`` and ``stderr`` contain things printed to the standard outputs.
+``output`` with the return value of the function call, ``stdout`` and ``stderr`` contain things printed to the standard outputs
+(see the section about :ref:`Result <result>` for more info about the capture of the standard outputs).
 If the task fails, :class:`arca.exceptions.BuildError` would be raised.
 
 By default, the :ref:`Current Environment Backend <backends_cur>` is used to run tasks,

docs/tasks.rst

@@ -69,6 +69,8 @@ The default value is 5 seconds.
 
 When a task exceeds a timeout, :class:`arca.exceptions.BuildTimeoutError` is raised.
 
+.. _result:
+
 Result
 ------
 
@@ -77,3 +79,7 @@ Anything that's json-serializable can be returned from the entrypoints.
 The :class:`arca.Result` instances contain three attributes.
 ``output`` contains the value returned from the entrypoint.
 ``stdout`` and ``stderr`` contain things written to the standard outputs.
+
+Arca uses :func:`contextlib.redirect_stdout` and :func:`contextlib.redirect_stderrr` to catch the standard outputs,
+which only redirect things written from standard Python code -- for example output from a subprocess is not caught.
+Due to the way backends launch tasks the callables cannot output anything that is not redirectable by these two context managers.