Merge pull request #55 from felix5572/master

add doc for class Task

doc/machine-auto.rst

@@ -57,13 +57,13 @@ machine:
             ssh connection port.
 
         key_filename: 
-            | type: ``str`` | ``NoneType``, optional, default: ``None``
+            | type: ``NoneType`` | ``str``, optional, default: ``None``
             | argument path: ``machine/remote_profile/key_filename``
 
             key_filename used by ssh connection
 
         passphrase: 
-            | type: ``str`` | ``NoneType``, optional, default: ``None``
+            | type: ``NoneType`` | ``str``, optional, default: ``None``
             | argument path: ``machine/remote_profile/passphrase``
 
             passphrase used by ssh connection

doc/task-auto.rst

@@ -0,0 +1,39 @@
+task: 
+    | type: ``dict``
+    | argument path: ``task``
+
+    command: 
+        | type: ``str``
+        | argument path: ``task/command``
+
+        A command to be executed of this task. The expected return code is 0.
+
+    task_work_path: 
+        | type: ``str``
+        | argument path: ``task/task_work_path``
+
+        The dir where the command to be executed.
+
+    forward_files: 
+        | type: ``list``
+        | argument path: ``task/forward_files``
+
+        The files to be uploaded in task_work_path before the task exectued.
+
+    backward_files: 
+        | type: ``list``
+        | argument path: ``task/backward_files``
+
+        The files to be download to local_root in task_work_path after the task finished
+
+    outlog: 
+        | type: ``NoneType`` | ``str``
+        | argument path: ``task/outlog``
+
+        The out log file name. redirect from stdout
+
+    errlog: 
+        | type: ``NoneType`` | ``str``
+        | argument path: ``task/errlog``
+
+        The err log file name. redirect from stderr

dpdispatcher/submission.py

@@ -220,7 +220,7 @@ def handle_unexpected_submission_state(self):
         for job in self.belonging_jobs:
             job.handle_unexpected_job_state()
 
-    # not used here, submit job is in handle_unexpected_submission_state.
+    # not used here, submitting job is in handle_unexpected_submission_state.
 
     # def submit_submission(self):
     #     """submit the job belonging to the submission.
@@ -403,6 +403,27 @@ def serialize(self):
         # task_dict['task_need_resources'] = self.task_need_resources
         return task_dict
 
+    @staticmethod
+    def arginfo():
+        doc_command = 'A command to be executed of this task. The expected return code is 0.'
+        doc_task_work_path = 'The dir where the command to be executed.'
+        doc_forward_files = 'The files to be uploaded in task_work_path before the task exectued.'
+        doc_backward_files = 'The files to be download to local_root in task_work_path after the task finished'
+        doc_outlog = 'The out log file name. redirect from stdout'
+        doc_errlog = 'The err log file name. redirect from stderr'
+
+        task_args = [
+            Argument("command", str, optional=False, doc=doc_command),
+            Argument("task_work_path", str, optional=False, doc=doc_task_work_path),
+            Argument("forward_files", list, optional=False, doc=doc_forward_files, default=[]),
+            Argument("backward_files", list, optional=False, doc=doc_backward_files, default=[]),
+            Argument("outlog", [None, str], optional=False, doc=doc_outlog, default='log'),
+            Argument("errlog", [None, str], optional=False, doc=doc_errlog, default='err'),
+        ]
+        task_format = Argument("task", dict, task_args)
+        return task_format
+
+
 class Job(object):
     """Job is generated by Submission automatically.
     A job ususally has many tasks and it may request computing resources from job scheduler systems.

scripts/script_gen_dargs_docs.py

@@ -3,7 +3,7 @@
 # import sys, os
 # sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..' )))
 # import dpdispatcher
-from dpdispatcher.submission import Resources
+from dpdispatcher.submission import Resources, Task
 from dpdispatcher.machine import Machine
 
 
@@ -16,4 +16,10 @@
 machine_dargs_doc = Machine.arginfo().gen_doc()
 with open('../doc/machine-auto.rst', 'w') as f:
     f.write(machine_dargs_doc)
+
+task_dargs_doc = Task.arginfo().gen_doc()
+with open('../doc/task-auto.rst', 'w') as f:
+    f.write(task_dargs_doc)
+
+
 # %%