From c0ce712be940bc781267e25a1d31db8855907205 Mon Sep 17 00:00:00 2001
From: you-n-g <you-n-g@users.noreply.github.com>
Date: Mon, 11 Oct 2021 15:38:18 +0800
Subject: [PATCH] more detailed docs for workflow (#639)

* more detailed docs for workflow

* add more detailed docs for workflow
---
 qlib/workflow/__init__.py | 34 +++++++++++++++++++++++++++-------
 qlib/workflow/recorder.py |  2 ++
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/qlib/workflow/__init__.py b/qlib/workflow/__init__.py
index 4b16bd387..8e20f4816 100644
--- a/qlib/workflow/__init__.py
+++ b/qlib/workflow/__init__.py
@@ -2,7 +2,7 @@
 # Licensed under the MIT License.
 
 from contextlib import contextmanager
-from typing import Text, Optional
+from typing import Any, Dict, Text, Optional
 from .expm import ExpManager
 from .exp import Experiment
 from .recorder import Recorder
@@ -380,11 +380,11 @@ class QlibRecorder:
         .. code-block:: Python
 
             # Case 1
-            with R.start('test'):
+            with R.start(experiment_name='test'):
                 recorder = R.get_recorder()
 
             # Case 2
-            with R.start('test'):
+            with R.start(experiment_name='test'):
                 recorder = R.get_recorder(recorder_id='2e7a4efd66574fa49039e00ffaefa99d')
 
             # Case 3
@@ -433,12 +433,18 @@ class QlibRecorder:
         """
         self.get_exp().delete_recorder(recorder_id, recorder_name)
 
-    def save_objects(self, local_path=None, artifact_path=None, **kwargs):
+    def save_objects(self, local_path=None, artifact_path=None, **kwargs: Dict[Text, Any]):
         """
         Method for saving objects as artifacts in the experiment to the uri. It supports either saving
         from a local file/directory, or directly saving objects. User can use valid python's keywords arguments
         to specify the object to be saved as well as its name (name: value).
 
+        In summary, this API is designs for saving **objects** to **the experiments management backend path**,
+        1. Qlib provide two methods to specify **objects**
+        - Passing in the object directly by passing with `**kwargs` (e.g. R.save_objects(trained_model=model))
+        - Passing in the local path to the object, i.e. `local_path` parameter.
+        2. `artifact_path` represents the  **the experiments management backend path**
+
         - If `active recorder` exists: it will save the objects through the active recorder.
         - If `active recorder` not exists: the system will create a default experiment, and a new recorder and save objects under it.
 
@@ -451,13 +457,20 @@ class QlibRecorder:
         .. code-block:: Python
 
             # Case 1
-            with R.start('test'):
+            with R.start(experiment_name='test'):
                 pred = model.predict(dataset)
                 R.save_objects(**{"pred.pkl": pred}, artifact_path='prediction')
+                rid = R.get_recorder().id
+            ...
+            R.get_recorder(recorder_id=rid).load_object("prediction/pred.pkl")  #  after saving objects, you can load the previous object with this api
 
             # Case 2
-            with R.start('test'):
-                R.save_objects(local_path='results/pred.pkl')
+            with R.start(experiment_name='test'):
+                R.save_objects(local_path='results/pred.pkl', artifact_path="prediction")
+                rid = R.get_recorder().id
+            ...
+            R.get_recorder(recorder_id=rid).load_object("prediction/pred.pkl")  #  after saving objects, you can load the previous object with this api
+
 
         Parameters
         ----------
@@ -465,7 +478,14 @@ class QlibRecorder:
             if provided, them save the file or directory to the artifact URI.
         artifact_path : str
             the relative path for the artifact to be stored in the URI.
+        **kwargs: Dict[Text, Any]
+            the object to be saved.
+            For example, `{"pred.pkl": pred}`
         """
+        if local_path is not None and len(kwargs) > 0:
+            raise ValueError(
+                "You can choose only one of `local_path`(save the files in a path) or `kwargs`(pass in the objects directly)"
+            )
         self.get_exp().get_recorder().save_objects(local_path, artifact_path, **kwargs)
 
     def load_object(self, name: Text):
diff --git a/qlib/workflow/recorder.py b/qlib/workflow/recorder.py
index 57d7a0f22..0bf6f4841 100644
--- a/qlib/workflow/recorder.py
+++ b/qlib/workflow/recorder.py
@@ -65,6 +65,8 @@ class Recorder:
         Save objects such as prediction file or model checkpoints to the artifact URI. User
         can save object through keywords arguments (name:value).
 
+        Please refer to the docs of qlib.workflow:R.save_objects
+
         Parameters
         ----------
         local_path : str