Repository: Parsl/parsl

Issue:
Consider removing emphasis on the `DataFlowKernel` in the docs
We might want to relegate discussion of the DFK to the more advanced section of the docs. For many applications, simply running `parsl.load` is sufficient. I strongly feel that as part of the class-based configuration shuffling we're doing, it will be simpler and less bug prone (on our side and user-side) to have the `Config` object be the only mode of specifying options (in other words, dispense with the ability to override options in the DFK constructor-- that removes places people can get confused about what precedence options have. There isn't really a cost; if they are importing a config and then overriding various options, it should be the same if they do it in the `Config` before loading or passing options to the constructor. Overriding options in the `Config` makes it explicit on their side what is going in.) If we _do_ go that route, then exposing the DFK to users seems even less necessary. I'm putting this out there now so I don't forget, but we should make the call after the class-based configs are worked out.


Discussion:
The way I see it, we have a limited quota of "user attention" people are willing to spend reading docs; the fewer vocab words we can throw at them, the more time they'll have for other things.
I agree with this.

Resolving patch:
diff --git a/parsl/dataflow/futures.py b/parsl/dataflow/futures.py
--- a/parsl/dataflow/futures.py
+++ b/parsl/dataflow/futures.py
@@ -1,6 +1,6 @@
 """This module implements the AppFutures.
 
-    We have two basic types of futures:
+We have two basic types of futures:
     1. DataFutures which represent data objects
     2. AppFutures which represent the futures on App/Leaf tasks.
 
@@ -110,7 +110,7 @@ def result(self, timeout=None):
 
         Waits for the result of the AppFuture
         KWargs:
-              timeout (int): Timeout in seconds
+        timeout (int): Timeout in seconds
         """
         try:
             if self.parent:


Test patch:
diff --git a/parsl/tests/test_staging/test_docs_1.py b/parsl/tests/test_staging/test_docs_1.py
new file mode 100644
--- /dev/null
+++ b/parsl/tests/test_staging/test_docs_1.py
@@ -0,0 +1,29 @@
+import pytest
+
+import parsl
+from parsl import App, File
+from parsl.configs.local_threads import config
+
+parsl.clear()
+parsl.load(config)
+
+
+@App('python')
+def convert(inputs=[], outputs=[]):
+    with open(inputs[0].filepath, 'r') as inp:
+        content = inp.read()
+        with open(outputs[0].filepath, 'w') as out:
+            out.write(content.upper())
+
+
+@pytest.mark.local
+def test():
+    # create an remote Parsl file
+    inp = File('ftp://www.iana.org/pub/mirror/rirstats/arin/ARIN-STATS-FORMAT-CHANGE.txt')
+
+    # create a local Parsl file
+    out = File('file:///tmp/ARIN-STATS-FORMAT-CHANGE.txt')
+
+    # call the convert app with the Parsl file
+    f = convert(inputs=[inp], outputs=[out])
+    f.result()
diff --git a/parsl/tests/test_staging/test_docs_2.py b/parsl/tests/test_staging/test_docs_2.py
new file mode 100644
--- /dev/null
+++ b/parsl/tests/test_staging/test_docs_2.py
@@ -0,0 +1,24 @@
+import pytest
+from parsl import App, File
+import parsl
+from parsl.configs.local_threads import config
+
+parsl.clear()
+parsl.load(config)
+
+
+@App('bash')
+def cat(inputs=[], stdout='stdout.txt'):
+    return 'cat %s' % (inputs[0])
+
+
+@pytest.mark.local
+def test():
+    # create a test file
+    open('/tmp/test.txt', 'w').write('Hello\n')
+
+    # create the Parsl file
+    parsl_file = File('file:///tmp/test.txt')
+
+    # call the cat app with the Parsl file
+    cat(inputs=[parsl_file])