update mddocs/user_guide/configuration.md.

add a example configuration file about how to configuration.

docs/sitemap.xml

@@ -4,7 +4,7 @@
 
     <url>
      <loc>None/</loc>
-     <lastmod>2016-11-26</lastmod>
+     <lastmod>2016-11-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
@@ -13,25 +13,25 @@
 
     <url>
      <loc>None/user_guide/installation/</loc>
-     <lastmod>2016-11-26</lastmod>
+     <lastmod>2016-11-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
     <url>
      <loc>None/user_guide/getting_started/</loc>
-     <lastmod>2016-11-26</lastmod>
+     <lastmod>2016-11-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
     <url>
      <loc>None/user_guide/sophon_style_python_docstrings/</loc>
-     <lastmod>2016-11-26</lastmod>
+     <lastmod>2016-11-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
     <url>
      <loc>None/user_guide/configuration/</loc>
-     <lastmod>2016-11-26</lastmod>
+     <lastmod>2016-11-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
@@ -41,19 +41,19 @@
 
     <url>
      <loc>None/about/release_notes/</loc>
-     <lastmod>2016-11-26</lastmod>
+     <lastmod>2016-11-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
     <url>
      <loc>None/about/contributing/</loc>
-     <lastmod>2016-11-26</lastmod>
+     <lastmod>2016-11-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
     <url>
      <loc>None/about/license/</loc>
-     <lastmod>2016-11-26</lastmod>
+     <lastmod>2016-11-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
@@ -62,7 +62,7 @@
 
     <url>
      <loc>None/api/sophon/API/</loc>
-     <lastmod>2016-11-26</lastmod>
+     <lastmod>2016-11-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 

docs/user_guide/configuration/index.html

@@ -152,12 +152,108 @@
 
         <li class="main active"><a href="#configuration">Configuration</a></li>
 
+            <li><a href="#code_dir">code_dir</a></li>
+
+            <li><a href="#template_dir">template_dir</a></li>
+
+            <li><a href="#build_dir">build_dir</a></li>
+
+            <li><a href="#repo_url">repo_url</a></li>
+
+            <li><a href="#branch">branch</a></li>
+
+            <li><a href="#style">style</a></li>
+
+            <li><a href="#pages">pages</a></li>
+
+            <li><a href="#page">page</a></li>
+
+            <li><a href="#tags">tags</a></li>
+
+            <li><a href="#tag">tag</a></li>
+
+            <li><a href="#functions">functions</a></li>
+
+            <li><a href="#classes">classes</a></li>
+
+            <li><a href="#classes_with_methods">classes_with_methods</a></li>
+
 
     </ul>
 </div></div>
             <div class="col-md-9" role="main">
 
-<h1 id="configuration">Configuration</h1></div>
+<h1 id="configuration">Configuration</h1>
+<p>A <code>sophon.yml</code> must contain following information.</p>
+<pre><code># 指定要抽取的代码的所在目录
+# 设置该目录的目的为了保证python module能够被导入
+# 可以没有，默认为.
+code_dir: .
+
+# 可以没有，默认为None
+# 如果没有模板，则所有tag对应的markdown doc对应添加在page文件末尾
+template_dir: templates
+
+# 可以没有，默认为./api
+build_dir:
+
+# 需要注意，上述两个路径，可以是绝对路径，可以是相对路径
+# 如果是相对路径，则是相对于本配置文件而言
+
+
+# 可以没有，默认为None
+pages:
+
+# 如果有page，则在build_dir/下生成名为page的文件
+- page: index.md
+
+- page: user/bb.md  # build_dir/user/bb.md
+  # 如果指定了该文件的模板，且template_dir存在，则使用模板。
+  # 如果指定了该文件的模板，而template_dir不存在，则报错
+  # 如果指定了该文件的模板，且template_dir存在，但模板文件不存在，则报错
+  # 如果没有指定该文件的模板，则不用模板，即创建空白page然后添加doc到文件末尾
+  template: user/bb.md  # template_dir/user/bb.md
+
+
+- page: cc.md
+  template: cc_temp.md
+  # 如果没有tags，则不从代码中生成markdown。
+    # 如果指定了模板文件，则page内容为模板文件的内容
+    # 如果没有指定模板文件，则page内容为空
+  # 如果有tags，则对每个tag生成markdown
+    # 如果指定了template，则将template文件中的每个{{tag标记}}置换为对应的markdown
+    # 如果没有指定template，tags的位置作用失效，所有markdown添加到文件末尾
+  tags:
+  # 每一个tag都有一个tag名，用于表示doc在文件中的位置
+  # 如果有tag名，则置换{{tag}}为markdown内容
+  # 如果没有tag名，则生成的doc添加在page的末尾
+  # 如果tag内容为空，则表示markdown doc为空字符串''
+
+  - tag: tag1
+    # 每个tag的doc生成顺序并不是tag内部决定，而是classes-&gt;classes_with_members-&gt;functions
+    functions:
+    - sss.gates.foo
+  - tag: tag2
+    classes:
+    - sss.gates.Dense
+    - sss.gates.Person
+    # 后续支持
+    # classes_with_members:
+</code></pre>
+
+<h3 id="code_dir">code_dir</h3>
+<h3 id="template_dir">template_dir</h3>
+<h3 id="build_dir">build_dir</h3>
+<h3 id="repo_url">repo_url</h3>
+<h3 id="branch">branch</h3>
+<h3 id="style">style</h3>
+<h3 id="pages">pages</h3>
+<h3 id="page">page</h3>
+<h3 id="tags">tags</h3>
+<h3 id="tag">tag</h3>
+<h3 id="functions">functions</h3>
+<h3 id="classes">classes</h3>
+<h3 id="classes_with_methods">classes_with_methods</h3></div>
         </div>
 
         <footer class="col-md-12">

docs/user_guide/getting_started/index.html

@@ -161,7 +161,7 @@
             <li><a href="#4-use-templates">4. Use templates</a></li>
 
 
-        <li class="main "><a href="#more-details">More details</a></li>
+        <li class="main "><a href="#5-more-details">5. More details</a></li>
 
 
     </ul>
@@ -409,7 +409,7 @@ <h2 id="4-use-templates">4. Use templates</h2>
 <li>if a tag don't have a name, then its Markdown text will append to the tail.</li>
 <li>if template Markdown file has a tag which is not specified in <code>sophon.yml</code>, Sophon will do nothing to it.</li>
 </ul>
-<h1 id="more-details">More details</h1>
+<h1 id="5-more-details">5. More details</h1>
 <p>More details of configuration can see <strong><a href="../configuration/">User Guide/Configuration</a></strong>.</p>
 <p>More details of docstring can see <strong><a href="../sophon_style_python_docstrings/">User Guide/Sophon Style Python docstrings</a></strong>.</p></div>
         </div>

mddocs/user_guide/configuration.md

@@ -1 +1,77 @@
-# Configuration
+# Configuration
+
+A `sophon.yml` must contain following information.
+
+
+```
+# 指定要抽取的代码的所在目录
+# 设置该目录的目的为了保证python module能够被导入
+# 可以没有，默认为.
+code_dir: .
+
+# 可以没有，默认为None
+# 如果没有模板，则所有tag对应的markdown doc对应添加在page文件末尾
+template_dir: templates
+
+# 可以没有，默认为./api
+build_dir:
+
+# 需要注意，上述两个路径，可以是绝对路径，可以是相对路径
+# 如果是相对路径，则是相对于本配置文件而言
+
+
+# 可以没有，默认为None
+pages:
+
+# 如果有page，则在build_dir/下生成名为page的文件
+- page: index.md
+
+- page: user/bb.md  # build_dir/user/bb.md
+  # 如果指定了该文件的模板，且template_dir存在，则使用模板。
+  # 如果指定了该文件的模板，而template_dir不存在，则报错
+  # 如果指定了该文件的模板，且template_dir存在，但模板文件不存在，则报错
+  # 如果没有指定该文件的模板，则不用模板，即创建空白page然后添加doc到文件末尾
+  template: user/bb.md  # template_dir/user/bb.md
+
+
+- page: cc.md
+  template: cc_temp.md
+  # 如果没有tags，则不从代码中生成markdown。
+    # 如果指定了模板文件，则page内容为模板文件的内容
+    # 如果没有指定模板文件，则page内容为空
+  # 如果有tags，则对每个tag生成markdown
+    # 如果指定了template，则将template文件中的每个{{tag标记}}置换为对应的markdown
+    # 如果没有指定template，tags的位置作用失效，所有markdown添加到文件末尾
+  tags:
+  # 每一个tag都有一个tag名，用于表示doc在文件中的位置
+  # 如果有tag名，则置换{{tag}}为markdown内容
+  # 如果没有tag名，则生成的doc添加在page的末尾
+  # 如果tag内容为空，则表示markdown doc为空字符串''
+
+  - tag: tag1
+    # 每个tag的doc生成顺序并不是tag内部决定，而是classes->classes_with_members->functions
+    functions:
+    - sss.gates.foo
+  - tag: tag2
+    classes:
+    - sss.gates.Dense
+    - sss.gates.Person
+    # 后续支持
+    # classes_with_members:
+```
+
+
+### code_dir
+### template_dir
+### build_dir
+### repo_url
+### branch
+### style
+### pages
+### page
+### tags
+### tag
+### functions
+### classes
+### classes_with_methods
+

mddocs/user_guide/getting_started.md

@@ -269,7 +269,7 @@ Note that:
 - if template Markdown file has a tag which is not specified in `sophon.yml`, Sophon will do nothing to it.
 
 
-# More details
+# 5. More details
 
 More details of configuration can see **[User Guide/Configuration](configuration.md)**.
 

sophon/cmd/sophon.example.yml

@@ -10,4 +10,6 @@ code_dir: .
 pages:
 - page: sophon/API.md
   tags:
-  - tag:
+  - tag: tag1
+  functions:
+  classes: