update docs for en/zhtw, en Usage is under construction

docs/en/build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: a12ac6d2c0fdf32982d982e3b27c6e7b
+config: 4f38c6751bc8f6d81d58e5131b3d3c66
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/en/build/html/About.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>About this project &mdash; easy_configer v2.3.2 documentation</title>
+  <title>About this project &mdash; easy_configer v2.5.3 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/custom.css" type="text/css" />
@@ -48,7 +48,10 @@
 <ul class="current">
 <li class="toctree-l1 current"><a class="current reference internal" href="#">About this project</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#preface">Preface ✨</a></li>
-<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction 📝</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction 📝</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#why-choice-easy-configer">🙋‍♂️ Why choice easy_configer ?</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="Installation.html">Installation</a></li>
@@ -93,16 +96,15 @@
 <h1>About this project<a class="headerlink" href="#about-this-project" title="Permalink to this heading"></a></h1>
 <section id="preface">
 <h2>Preface ✨<a class="headerlink" href="#preface" title="Permalink to this heading"></a></h2>
-<p>easy_configer version : 2.5.2</p>
-<blockquote>
-<div><p>Note : version 2.5.2 just add new document</p>
-</div></blockquote>
+<p>easy_configer version : 2.5.6</p>
 <p>Configeruating the program in an easy-way</p>
 <p>I’m willing to provide a light-weight solution for configurating your python program.
 Hope this repository make every user control their large project with easier ~ ~</p>
 </section>
 <section id="introduction">
 <h2>Introduction 📝<a class="headerlink" href="#introduction" title="Permalink to this heading"></a></h2>
+<section id="why-choice-easy-configer">
+<h3>🙋‍♂️ Why choice easy_configer ?<a class="headerlink" href="#why-choice-easy-configer" title="Permalink to this heading"></a></h3>
 <p>With the python project go into large-scale, a lot of argument will be required to control the complex business logic, user may need a simple way to load configurations through a file eventually. Their exists various package cover part of function and offer some solution to tackle the mentioned problem.</p>
 <p><strong>Unfortunately, I can not find a solution for load &amp; use the argument in simple manner at least.</strong>   Instead, most of the config-tools seems only works for the specific goal, then cause the code more longer and hard to read.</p>
 <p>For example :</p>
@@ -122,25 +124,44 @@ <h2>Introduction 📝<a class="headerlink" href="#introduction" title="Permalink
 <span class="o">...</span>
 <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
 <span class="n">args</span><span class="o">.</span><span class="n">lucky_num</span>
+
+<span class="c1">## Omegaconf</span>
+<span class="kn">from</span> <span class="nn">omegaconf</span> <span class="kn">import</span> <span class="n">OmegaConf</span>
+<span class="n">conf</span> <span class="o">=</span> <span class="n">OmegaConf</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="s1">&#39;source/example.yaml&#39;</span><span class="p">)</span>
+<span class="n">conf</span><span class="o">.</span><span class="n">player</span><span class="o">.</span><span class="n">height</span>
 </pre></div>
 </div>
-<p>That leverage me to package my solution for solving this issue. The easy_config will cover the following attributes :</p>
+<p>Except omegaconf, most of config tools have much redundant syntax to load and access config arguments.
+However, omegaconf also have several draw backs :</p>
+<ol class="arabic simple">
+<li><p>Too much dependencies (version competible may become issue!)</p></li>
+<li><p>Dynamic config loading system is hard to trace (which config overwrite my default setup ?)</p></li>
+<li><p>Non-native container (it apply Mappable object, so need to apply to_container for further convertion)</p></li>
+</ol>
+<p>That leverage me to package my solution for solving those issue. easy_configer have several advantages :</p>
+<ol class="arabic simple">
+<li><p>Zero-dependency!! (except you want to convert easy_configer to other config tools instance)</p></li>
+<li><p>Flexible apply <code class="code docutils literal notranslate"><span class="pre">allow_overwrite=False</span></code>, you can easily detect the overwritted arguments..</p></li>
+<li><p>Our container inherit pure python dict! Most of dict methods are also online ~</p></li>
+</ol>
+<p>My solution also cover the following attributes :</p>
 <ol class="arabic simple">
-<li><p><strong>Hierachical section config (nested dictionary)</strong></p></li>
-<li><p><strong>Accept multiple config file in dynamic loading manner</strong></p></li>
-<li><p><strong>Support customized class (initialized by keyword arguments)</strong></p></li>
-<li><p><strong>Commend-line update all declared-value wherever it belong, even in hierachical section</strong></p></li>
+<li><p><strong>Hierachical section config (nested dict-like config)</strong></p></li>
+<li><p><strong>Accept multiple config file in dynamic loading manner (similar with omegaconf)</strong></p></li>
+<li><p><strong>Support customized class (initialized by list or keyword arguments)</strong></p></li>
+<li><p><strong>Commend-line add/update declared arguments/sections (even in hierachical section)</strong></p></li>
 <li><p><strong>Support the absl style FLAGS functionality (declare once, use anywhere)</strong></p></li>
 </ol>
 <p>And, of course the following attribute will also be supported :</p>
 <ul class="simple">
 <li><p>dot-access of any arguments (even in nested dictionary)</p></li>
 <li><p>inline comment ‘#’, now you can write comment in everyline ~</p></li>
-<li><p>support config argument interpolation, inline-intepolation is also online now ~</p></li>
-<li><p>support config conversion, which turn easy_config into the other kind of config package (omegaconf, argparse, …, etc.)</p></li>
-<li><p>support hierachical configuration system with dynamic loading ~</p></li>
+<li><p>support config argument interpolation (even in nested dictionary)!</p></li>
+<li><p>support config conversion, feel free to use easy_config or the other config tools (omegaconf, argparse, …, etc.)</p></li>
+<li><p>support omegaconf-like dynamic config loading system ~</p></li>
 </ul>
 </section>
+</section>
 </section>
 
 

docs/en/build/html/Installation.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Installation &mdash; easy_configer v2.3.2 documentation</title>
+  <title>Installation &mdash; easy_configer v2.5.3 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/custom.css" type="text/css" />
@@ -99,7 +99,7 @@ <h2>How to install ? ⚙️<span class="raw-html-m2r"><br></span><a class="heade
 </dl>
 </li>
 <li><dl class="simple">
-<dt><strong>install from source code</strong> <span class="raw-html-m2r"><br></span></dt><dd><p>clone the project from github : <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">repo-link</span></code>
+<dt><strong>install from source code</strong> <span class="raw-html-m2r"><br></span></dt><dd><p>clone the project from github : <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">https://github.com/HuangChiEn/easy_config.git</span></code>
 Chage to the root directory of the cloned project, and type <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-e</span> <span class="pre">.</span></code></p>
 </dd>
 </dl>

docs/en/build/html/Metainfo.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Meta information &mdash; easy_configer v2.3.2 documentation</title>
+  <title>Meta information &mdash; easy_configer v2.5.3 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/custom.css" type="text/css" />
@@ -96,25 +96,25 @@ <h1>Meta information<a class="headerlink" href="#meta-information" title="Permal
 <section id="newly-update-features">
 <h2>Newly update features 🚀<a class="headerlink" href="#newly-update-features" title="Permalink to this heading"></a></h2>
 <ol class="arabic simple">
-<li><p>Easy-configer pass all test-case, and v2.5.2 is the stable version.</p></li>
-<li><p>Integrate argument intepolation with using ${cfg} notation</p></li>
-<li><p>Integrate enviroment variable intepolation with using ${cfg} notation</p></li>
+<li><p>v2.5.4 is basically stable, but we add more test case in this version (it’s more stable now) ~</p></li>
+<li><p>Apply ${cfg}, ${env} as argument and enviroment intepolation notation, respectively.</p></li>
+<li><p>Apply AttributeDict container (it inherit pure python dict) to store non-flatten arguments!</p></li>
 </ol>
 </section>
 <hr class="docutils" />
 <section id="todo-list">
 <h2>TODO List 🔨<a class="headerlink" href="#todo-list" title="Permalink to this heading"></a></h2>
 <ol class="arabic simple">
-<li><p>Better <strong>config syntax</strong> in easy-config ~</p></li>
+<li><p>Apply AttributeDict for config instance</p></li>
 </ol>
 <blockquote>
-<div><p>next version released features v 2.6</p>
+<div><p>next version released features v 3.0</p>
 </div></blockquote>
 </section>
 <section id="bug-fixed">
 <h2>Bug Fixed 🐛<a class="headerlink" href="#bug-fixed" title="Permalink to this heading"></a></h2>
-<p>Due to safty policy, we rollback the feature “single line python code interpreter”..
-Hot-fix config overrided bug, add flag for support allow_override..</p>
+<p>Hot-fix AttributeDict to raise NoAttributeError,
+Hot-fix config overwrite bug, add flag for support allow_overwrite..</p>
 </section>
 <hr class="docutils" />
 <section id="simple-unittest">

docs/en/build/html/Quick.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Quick start &mdash; easy_configer v2.3.2 documentation</title>
+  <title>Quick start &mdash; easy_configer v2.5.3 documentation</title>
       <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
       <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
       <link rel="stylesheet" href="_static/custom.css" type="text/css" />
@@ -120,8 +120,24 @@ <h2>Handy example of config file 🥂<a class="headerlink" href="#handy-example-
 <span class="nb">print</span><span class="p">(</span> <span class="sa">f</span><span class="s2">&quot;Linear equation with x=</span><span class="si">{</span><span class="n">x</span><span class="si">}</span><span class="s2"> : </span><span class="si">{</span><span class="w"> </span><span class="n">lin_equ</span><span class="p">(</span><span class="n">x</span><span class="p">)</span><span class="w"> </span><span class="si">}</span><span class="s2">&quot;</span> <span class="p">)</span>
 </pre></div>
 </div>
-<p>In larger project, we may write a config file to control the program, so that the config will become easy to trace, check and debug. In here, we first prepare an config called <code class="docutils literal notranslate"><span class="pre">test_cfg.ini</span></code> in the working directory.
-<em>For easy-config file, there’re two type of argument : flatten argument, hierachical argument.</em> You can see that flatten argument is placed in first shallow level, and the argument could be easily accessed by dot operator. Besides flatten argument, all of hierachical argument will be placed in python dict object, thus accessing each argument by key string!</p>
+<blockquote>
+<div><p>If you want to overwrite previous config, <em>apply twice</em> <code class="docutils literal notranslate"><span class="pre">cfg.cfg_from_str</span></code> with <code class="docutils literal notranslate"><span class="pre">allow_overwrite=True</span></code> flag IS NOT a recommended way.
+In easy-configer, we provide 2 way to do that. The standard way is <em>declaring 2 config and apply config merging method</em> to get the updated config.
+The other way is similar with omegaconf to import sub-config in dynamic manner,  however you still need to set flag <code class="docutils literal notranslate"><span class="pre">allow_overwrite=True</span></code> in <code class="docutils literal notranslate"><span class="pre">cfg.cfg_from_ini</span></code>.</p>
+</div></blockquote>
+<p>Although writing a string config in python is convenient, it only suitable for the project in smaller scale.
+In large project, we may write a config file to control the program, so that we will be easy to trace, check and debug the config.
+We are going to prepare a sample config called <code class="docutils literal notranslate"><span class="pre">test_cfg.ini</span></code> in the working directory and describe how we work with chatbot roughly.</p>
+<p>In easy-configer, there’re two type of argument in config : flatten argument, hierachical argument.
+You will see that the flatten arguments are directly placed in config and doesn’t belong any section (namely in first level).
+In contrast, the hierachical arguments will be placed in section (i.e. <code class="docutils literal notranslate"><span class="pre">[db_setup]</span></code>) with any kind of depth,
+the arguments under the section will be wrapped by a container (<cite>easy_configer.utils.Container.AttributeDict</cite>) similar with pure python <code class="docutils literal notranslate"><span class="pre">dict</span></code>.</p>
+<p>To form a hierachical argument in nested section, we apply toml-like syntax to describe the nested section (i.e. <code class="docutils literal notranslate"><span class="pre">[bknd_srv.mod_params]</span></code> is belong to <code class="docutils literal notranslate"><span class="pre">[bknd_srv]</span></code> parent section).
+The arguments in nested section are also wrapped by nested AttributeDict. Besides you can access all kind of arguments by the simple dot-operator, however, we still recommend you to use key-string as pure python dict.</p>
+<blockquote>
+<div><p>Note that the recommended way to access the argument is <strong>still</strong> key-string access <code class="docutils literal notranslate"><span class="pre">cfger.args['#4$%-var']</span></code>, as you may notice,
+dot-access doesn’t support <strong>ugly</strong> variable name (<code class="docutils literal notranslate"><span class="pre">cfger.#4$%-var</span></code>, as variable name is invalid in python intepreter).</p>
+</div></blockquote>
 <div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="c1"># ./test_cfg.ini</span>
 <span class="c1"># &#39;#&#39; denote comment line, the inline comment is also supported!</span>
 
@@ -133,9 +149,9 @@ <h2>Handy example of config file 🥂<a class="headerlink" href="#handy-example-
 <span class="c1"># define &#39;hierachical&#39; arguments :</span>
 <span class="c1"># the &#39;section&#39; is the key of accessing dict value and could be defined as follows :</span>
 <span class="k">[db_setup]</span>
-<span class="w">    </span><span class="na">db_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">$serv_host</span>
+<span class="w">    </span><span class="na">db_host</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">${cfg.serv_host}:80@str</span>
 <span class="w">    </span><span class="c1"># first `export mongo_port=5566` in your bash, then support os.env interpolation!</span>
-<span class="w">    </span><span class="na">db_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">$Env.mongo_port</span>
+<span class="w">    </span><span class="na">db_port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">${env.mongo_port}</span>
 <span class="w">    </span><span class="na">snap_shot</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">True</span>
 
 <span class="c1"># and then define second section for backend server..</span>
@@ -147,12 +163,16 @@ <h2>Handy example of config file 🥂<a class="headerlink" href="#handy-example-
 <span class="w">    </span><span class="k">[bknd_srv.mod_params]</span>
 <span class="w">        </span><span class="na">log_hist</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">False</span>
 <span class="w">        </span><span class="na">tempeture</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">1e-4</span>
-<span class="w">        </span><span class="na">model_mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">$bknd_srv.chat_mode</span><span class="w">  </span><span class="c1"># hierachical args interpolation</span>
+<span class="w">        </span><span class="na">model_mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">${cfg.bknd_srv.chat_mode}</span><span class="w">  </span><span class="c1"># hierachical args interpolation</span>
 </pre></div>
 </div>
 <p><span class="raw-html-m2r"><br></span></p>
 <p>Now, we’re free to launch the chatbot via <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">quick_start.py</span></code> (<em>quick_start.py in work directory</em>)!
 However, you can also override the arguemnts via commendline <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">quick_start.py</span> <span class="pre">serv_port=7894</span></code></p>
+<blockquote>
+<div><p>Note that <strong>update argument</strong> from commendline is naturally permitted, but overwrite <strong>the section</strong> IS NOT!
+If you also want to overwrite the section, you need to set flag <code class="docutils literal notranslate"><span class="pre">allow_overwrite=True</span></code>.</p>
+</div></blockquote>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span>
 
 <span class="c1"># main_block</span>