From 9a175d7507811af5675ad1287830abe7810065b6 Mon Sep 17 00:00:00 2001
From: you-n-g <you-n-g@users.noreply.github.com>
Date: Tue, 12 Oct 2021 11:58:27 +0800
Subject: [PATCH] improve the doc of auto init (#541)

* improve the doc of auto init

* Update setup.py

* Update setup.py

* change cvxpy version

Co-authored-by: Wangwuyi123 <51237097+Wangwuyi123@users.noreply.github.com>
---
 qlib/__init__.py | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/qlib/__init__.py b/qlib/__init__.py
index efa89b153..107819860 100644
--- a/qlib/__init__.py
+++ b/qlib/__init__.py
@@ -6,6 +6,7 @@ _version_path = Path(__file__).absolute().parent / "VERSION.txt"  # This file is
 __version__ = _version_path.read_text(encoding="utf-8").strip()
 __version__bak = __version__  # This version is backup for QlibConfig.reset_qlib_version
 import os
+from typing import Union
 import yaml
 import logging
 import platform
@@ -158,7 +159,7 @@ def init_from_yaml_conf(conf_path, **kwargs):
     init(default_conf, **config)
 
 
-def get_project_path(config_name="config.yaml", cur_path=None) -> Path:
+def get_project_path(config_name="config.yaml", cur_path: Union[Path, str, None] = None) -> Path:
     """
     If users are building a project follow the following pattern.
     - Qlib is a sub folder in project path
@@ -187,6 +188,7 @@ def get_project_path(config_name="config.yaml", cur_path=None) -> Path:
     """
     if cur_path is None:
         cur_path = Path(__file__).absolute().resolve()
+    cur_path = Path(cur_path)
     while True:
         if (cur_path / config_name).exists():
             return cur_path
@@ -202,6 +204,40 @@ def auto_init(**kwargs):
         - The parsing process will be affected by the `conf_type` of the configuration file
     - Init qlib with default config
     - Skip initialization if already initialized
+
+    :**kwargs: it may contain following parameters
+                cur_path: the start path to find the project path
+
+    Here are two examples of the configuration
+
+    Example 1)
+    If you want create a new project-specific config based on a shared configure, you can use  `conf_type: ref`
+
+    .. code-block:: yaml
+
+        conf_type: ref
+        qlib_cfg: '<shared_yaml_config_path>'
+        # following configs in `qlib_cfg_update` is project=specific
+        qlib_cfg_update:
+            exp_manager:
+                class: "MLflowExpManager"
+                module_path: "qlib.workflow.expm"
+                kwargs:
+                    uri: "file://<your mlflow experiment path>"
+                    default_exp_name: "Experiment"
+
+    Example 2)
+    If you wan to create simple a stand alone config, you can use following config(a.k.a `conf_type: origin`)
+
+    .. code-block:: python
+
+        exp_manager:
+            class: "MLflowExpManager"
+            module_path: "qlib.workflow.expm"
+            kwargs:
+                uri: "file://<your mlflow experiment path>"
+                default_exp_name: "Experiment"
+
     """
     kwargs["skip_if_reg"] = kwargs.get("skip_if_reg", True)