update readme

Author: reiase

docs/quick_start.md

@@ -1,134 +1,118 @@
-Quick Start
-===========
+# 快速开始
 
-HyperParameter is a configuration and parameter management library for Python. HyperParameter provides the following features:
+`HyperParameter` 是一个配置参数管理框架，为 Python 应用提供超参配置与参数调优等功能。可通过如下命令快速安装：
 
-1. `HyperParameter` class, providing object-style api for accessing dict data and handling undefine parameters with default values;
-2. `param_scope` context manager, maintains a thread-safe `HyperParameter` and manage parameter modifications with nested `param_scope`;
-3. `auto_param` decorator, allowing default parameters of a function or class to be supplied from `param_scope`;
-
-HyperParameter is particularly well suited for machine learning experiments and related systems, which have many parameters and nested codes.
+```shell
+pip install hyperparameter
+```
 
-`HyperParameter`
-----------------
+主要特性：
 
-### create hyperparameter
+1. `param_scope` 上下文，向 Python 应用提供线程安全的、可嵌套的参数管理上下文；提供对象化的树状参数管理，并支持默认值；
 
 ```python
->>> from hyperparameter import HyperParameter
->>> hp = HyperParameter(param1=1, param2="A")
->>> hp
-{'param1': 1, 'param2': 'A'}
+>>> from hyperparameter import param_scope
+>>> with param_scope(param1=1) as ps:
+...     print(f"param1={ps.param1()}, param2={ps.param2('undefined')}")
+param1=1, param2=undefined
 
 ```
 
-### access parameters in hyperparameter
-
-we can access the parameter stored in HyperParameter with object-style API:
+2. `auto_param` 装饰器，自动将函数（或者 class）的默认参数转化为超参，并接受`param_scope`的参数控制；
 
 ```python
->>> hp.param1
-1
-
->>> hp.param2
-'A'
-
-```
+>>> from hyperparameter import auto_param, param_scope
+>>> @auto_param
+... def foo(a, b="default"):
+...     print(f"a={a}, b={b}")
 
-nested parameters are also supported:
+>>> foo(0)
+a=0, b=default
 
-```python
->>> hp = HyperParameter(param1=1, obj2={"prop3": 3})
->>> hp.obj2.prop3
-3
+>>> with param_scope(**{"foo.b": "modified"}):
+...     foo(0)
+a=0, b=modified
 
 ```
 
-### access undefined parameter
+## 超参配置
 
-Undefined parameter is treated as false in `if` statement: 
+1. 通过`param_scope`可以直接读取超参配置，而无需任何配置：
 
 ```python
->>> if not hp.undefined_param: print("param not defined")
-param not defined
+>>> from hyperparameter import param_scope
+>>> def foo():
+...     # read parameter from param_scope
+...     p = param_scope.param("default")
+...     p2 = param_scope.namespace.param2("default2")
+...     print(f"p={p}, p2={p2}")
 
 ```
 
-The hyperparameter object is a `Callable`, and will be turned into `safe-mode` when called. In safe-mode the users must provide a default value when accessing parameters.
+在上述函数`foo`中，尝试访问名为`param`的超参，超参默认值为`default`。`param_scope`首先尝试从上下文中读取同名参数并返回给调用者，若超参未定义则返回默认值。为了更好的组织参数，也可以给参数名添加命名空间`namespace.param`。命名空间也支持嵌套多层，比如`namespace.subspace.param`。
 
-```python
->>> hp().undefined_param("default_value")
-'default_value'
+2. 通过`param_scope`传递超参
 
-```
+```python
+# call `foo` with default parameter
+>>> foo()
+p=default, p2=default2
 
-`param_scope`
--------------
+# call `foo` with modified parameter
+>>> with param_scope("namespace.param2=modified"):
+...     foo()
+p=default, p2=modified
 
-### manage hyper-parameters with `param_scope`
+```
 
-`param_scope` create a `HyperParameter` object for the context it manages:
+通过`with param_scope(...)`传递参数的时候支持两种语法，字符串语法与字典语法。字典语法如下所示：
 
 ```python
->>> from hyperparameter import param_scope
->>> with param_scope(param1=1, param2="A") as ps:
-...     ps.param1
-1
+# call `foo` with modified parameter
+>>> with param_scope(**{
+...         "param": "modified",
+...         "namespace": {"param2": "modified2"}
+...     }):
+...     foo()
+p=modified, p2=modified2
 
 ```
 
-### access hyper-parameter in functions
+字典语法适合配合配置文件使用。
 
-`param_scope` is often used to configure the behavior of a function.
+3. `param_scope`可以穿透多层函数调用传递参数：
 
 ```python
->>> def foo(): # access parameter
-...     ps = param_scope.current()
-...     return ps.param1
-
->>> def foo_with_default(): # access parameter with default value
-...     ps = param_scope.current()
-...     return ps().param1(2) # default value is `2`
-
->>> with param_scope(param1=1, param2="A") as ps:
+>>> def bar():
 ...     foo()
-1
-
->>> with param_scope(param1=1, param2="A") as ps:
-...     foo_with_default()
-1
 
->>> with param_scope(param2="A") as ps:
-...     foo_with_default()
-2
+# call `foo` within nested function call
+>>> with param_scope("namespace.param2=modified"):
+...     bar()
+p=default, p2=modified
 
 ```
 
-`auto_param`
-------------
+## 自动超参
 
-### Define a function with `auto_param` decorator
-
-`auto_param` provides an easier way to define a configurable function. The configurable parameters and their default values are defined with kwargs if `auto_param` is used.
+1. `auto_param` 可以自动为函数（或者 class）添加超参配置功能
 
 ```python
 >>> from hyperparameter import auto_param
 >>> @auto_param
-... def foo(a, b=1, c=2):
-...     return (a, b, c)
+... def foo(param, param1=1):
+...     print(f"param={param}, param1={param1}")
 
 >>> foo(0)
-(0, 1, 2)
+param=0, param1=1
 
 ```
 
-### config function default parameter with `param_scope`
-
-We can config the default behavior of a function with `param_scope`. Since the `param_scope` API is scoped and thread-safe, we can use it without too much warry.
+2. 通过`param_scope`向`auto_param`传递参数：
 
 ```python
->>> with param_scope(**{"foo.b": 0}):
+>>> with param_scope(**{"foo.param1": 0}):
 ...     foo(0)
-(0, 0, 2)
+param=0, param1=0
 
-```
+```

docs/quick_start.zh.md

@@ -13,7 +13,7 @@ pip install hyperparameter
 ```python
 >>> from hyperparameter import param_scope
 >>> with param_scope(param1=1) as ps:
-...     print(f"param1={ps.param1}, param2={ps.param2('undefined')}")
+...     print(f"param1={ps.param1()}, param2={ps.param2('undefined')}")
 param1=1, param2=undefined
 
 ```