update mddcos/about/release_notes.md and license.md

monitor1379 · Dec 3, 2016 · 582a28f · 582a28f
1 parent 64ae8e2
commit 582a28f
Show file tree

Hide file tree

Showing 18 changed files with 322 additions and 408 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,6 +3,8 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+.idea/
+
 # C extensions
 *.so
 

diff --git a/docs/about/license/index.html b/docs/about/license/index.html
@@ -100,12 +100,6 @@
 
 
 
-<li >
-    <a href="../contributing/">Contributing</a>
-</li>
-
-
-
 <li class="active">
     <a href="./">License</a>
 </li>
@@ -131,7 +125,7 @@
                     </a>
                 </li>
                 <li >
-                    <a rel="next" href="../contributing/">
+                    <a rel="next" href="../release_notes/">
                         <i class="fa fa-arrow-left"></i> Previous
                     </a>
                 </li>
@@ -154,7 +148,23 @@
 </div></div>
             <div class="col-md-9" role="main">
 
-</div>
+<p>MIT License</p>
+<p>Copyright (c) 2016 邓振鹏</p>
+<p>Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:</p>
+<p>The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.</p>
+<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.</p></div>
         </div>
 
         <footer class="col-md-12">

diff --git a/docs/about/release_notes/index.html b/docs/about/release_notes/index.html
@@ -100,12 +100,6 @@
 
 
 
-<li >
-    <a href="../contributing/">Contributing</a>
-</li>
-
-
-
 <li >
     <a href="../license/">License</a>
 </li>
@@ -136,7 +130,7 @@
                     </a>
                 </li>
                 <li >
-                    <a rel="prev" href="../contributing/">
+                    <a rel="prev" href="../license/">
                         Next <i class="fa fa-arrow-right"></i>
                     </a>
                 </li>
@@ -150,11 +144,25 @@
             <div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary">
     <ul class="nav bs-sidenav">
 
+        <li class="main active"><a href="#release-notes">Release Notes</a></li>
+
+            <li><a href="#maintenance-team">Maintenance Team</a></li>
+
+            <li><a href="#version-0102016-12-03">Version 0.1.0(2016-12-03)</a></li>
+
+
     </ul>
 </div></div>
             <div class="col-md-9" role="main">
 
-</div>
+<h1 id="release-notes">Release Notes</h1>
+<h2 id="maintenance-team">Maintenance Team</h2>
+<p>The current and past members of Sophon team:</p>
+<ul>
+<li><a href="https://github.com/monitor1379">Zhenpeng Deng(monitor1379)</a></li>
+</ul>
+<h2 id="version-0102016-12-03">Version 0.1.0(2016-12-03)</h2>
+<p>First release version.</p></div>
         </div>
 
         <footer class="col-md-12">

diff --git a/docs/api/sophon/API/index.html b/docs/api/sophon/API/index.html
@@ -100,12 +100,6 @@
 
 
 
-<li >
-    <a href="../../../about/contributing/">Contributing</a>
-</li>
-
-
-
 <li >
     <a href="../../../about/license/">License</a>
 </li>

diff --git a/docs/index.html b/docs/index.html
@@ -100,12 +100,6 @@
 
 
 
-<li >
-    <a href="about/contributing/">Contributing</a>
-</li>
-
-
-
 <li >
     <a href="about/license/">License</a>
 </li>

diff --git a/docs/mkdocs/search_index.json b/docs/mkdocs/search_index.json
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
@@ -4,7 +4,7 @@
 
     <url>
      <loc>None/</loc>
-     <lastmod>2016-11-30</lastmod>
+     <lastmod>2016-12-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
@@ -13,25 +13,25 @@
 
     <url>
      <loc>None/user_guide/installation/</loc>
-     <lastmod>2016-11-30</lastmod>
+     <lastmod>2016-12-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
     <url>
      <loc>None/user_guide/getting_started/</loc>
-     <lastmod>2016-11-30</lastmod>
+     <lastmod>2016-12-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
     <url>
      <loc>None/user_guide/sophon_style_python_docstrings/</loc>
-     <lastmod>2016-11-30</lastmod>
+     <lastmod>2016-12-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
     <url>
      <loc>None/user_guide/configuration/</loc>
-     <lastmod>2016-11-30</lastmod>
+     <lastmod>2016-12-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
@@ -41,19 +41,13 @@
 
     <url>
      <loc>None/about/release_notes/</loc>
-     <lastmod>2016-11-30</lastmod>
-     <changefreq>daily</changefreq>
-    </url>
-
-    <url>
-     <loc>None/about/contributing/</loc>
-     <lastmod>2016-11-30</lastmod>
+     <lastmod>2016-12-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
     <url>
      <loc>None/about/license/</loc>
-     <lastmod>2016-11-30</lastmod>
+     <lastmod>2016-12-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
@@ -62,7 +56,7 @@
 
     <url>
      <loc>None/api/sophon/API/</loc>
-     <lastmod>2016-11-30</lastmod>
+     <lastmod>2016-12-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 

diff --git a/docs/user_guide/configuration/index.html b/docs/user_guide/configuration/index.html
@@ -100,12 +100,6 @@
 
 
 
-<li >
-    <a href="../../about/contributing/">Contributing</a>
-</li>
-
-
-
 <li >
     <a href="../../about/license/">License</a>
 </li>
@@ -175,17 +169,11 @@
 
             <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>
 
-            <li><a href="#hierarchy-of-configuration-file">Hierarchy of configuration file</a></li>
-
-            <li><a href="#simple-example-of-configuration-file">Simple example of configuration file</a></li>
-
-            <li><a href="#complex-example-of-configuration-file">Complex example of configuration file</a></li>
+            <li><a href="#functions">functions</a></li>
 
 
     </ul>
@@ -251,7 +239,7 @@ <h2 id="pages">pages</h2>
 <hr />
 <h2 id="page">page</h2>
 <p><code>page</code>表示一个生成的API Markdown文档。格式为：</p>
-<pre><code># filename: /home/user/sophon.yml
+<pre><code class="text"># filename: /home/user/sophon.yml
 build_dir: api
 template_dir: templates
 
@@ -282,78 +270,60 @@ <h2 id="tags">tags</h2>
 <hr />
 <h2 id="tag">tag</h2>
 <p><code>tag</code>表示一个标记，通常结合模板文件来使用，表示生成的API Markdown text应该插入到模板文件的哪个地方。</p>
-<p>举个例子：</p>
-<pre><code># filename: /home/user/sophon.yml
+<p>举个例子,假设模板文件<code>/home/user/templates/bb.md</code>内容为：</p>
+<pre><code class="text"># Hello World
+
+{{tag0}}
+
+## Hello Sophon
+
+{{tag1}}
+</code></pre>
+
+<p>配置文件为：</p>
+<pre><code class="text"># filename: /home/user/sophon.yml
 build_dir: api
 template_dir: templates
 
 pages:
 - page: test/aa.md
   template: bb.md
   tags:
-  - tag:
-  functions:
-
+  - tag: tag0
+    functions:
+    - mod.func
+  - tag: tag1
+    classes:
+    - mod.clazz
 </code></pre>
 
-<hr />
-<h2 id="functions">functions</h2>
+<p>则运行Sophon之后：</p>
+<ul>
+<li>Sophon会先读取模板文件<code>/home/user/templates/bb.md</code>里的内容；</li>
+<li>然后将标记<code>{{tag0}}</code>替换为函数<code>mod.func</code>的API Markdown text；</li>
+<li>再将标记<code>{{tag1}}</code>替换为类<code>mod.clazz</code>的API Markdown text；</li>
+<li>最后将内容写入<code>/home/user/api/test/aa.md</code>中。</li>
+</ul>
+<p>注意的是，以下几种情况中，该tag下包含的函数、类的API Markdown text会依次添加在文件末尾，而不是替换掉模板文件中的<code>{{tag}}</code>：</p>
+<ul>
+<li>配置文件中指定了一个tag，但是没有给tag名时；</li>
+<li>配置文件中指定了一个tag，但是在模板文件中不存在该tag标记时；</li>
+<li>配置文件中指定了一个tag，但是该tag所属的<code>page</code>没有使用模板文件时。</li>
+</ul>
+<p>每个tag所包含的API按照固定顺序classes-&gt;classes_with_members-&gt;functions依次生成API Markdown text。</p>
+<p>另外，Sophon不会对存在于模板文件但是却没有在配置文件中指定的tag作任何处理，也就是一切以配置文件为准。</p>
 <hr />
 <h2 id="classes">classes</h2>
+<p><code>classes</code>是一个包含多个类的包路径的列表。</p>
+<p>Sophon在生成一个类的API文档时，只会选择该类的docstring来生成该类构造函数的API Markdown text，
+并不包括该类的成员函数与方法。</p>
 <hr />
 <h2 id="classes_with_methods">classes_with_methods</h2>
+<p><code>classes_with_methods</code>是一个包含多个函数的包路径的列表。</p>
+<p>Sophon在生成一个类的API文档时，会生成包括构造函数在内的该类所有公有成员函数与方法的API Markdown text。</p>
 <hr />
-<h2 id="hierarchy-of-configuration-file">Hierarchy of configuration file</h2>
-<pre><code>
-# 可以没有，默认为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>
-
-<h2 id="simple-example-of-configuration-file">Simple example of configuration file</h2>
-<p>Let's see an simple example of configuration file.</p>
-<pre><code>TODO
-</code></pre>
-
-<h2 id="complex-example-of-configuration-file">Complex example of configuration file</h2>
-<p>Let's see an complex example of configuration file.</p>
-<pre><code>TODO
-</code></pre></div>
+<h2 id="functions">functions</h2>
+<p><code>functions</code>是一个包含多个函数的包路径的列表。</p></div>
         </div>
 
         <footer class="col-md-12">

diff --git a/docs/user_guide/getting_started/index.html b/docs/user_guide/getting_started/index.html
@@ -100,12 +100,6 @@
 
 
 
-<li >
-    <a href="../../about/contributing/">Contributing</a>
-</li>
-
-
-
 <li >
     <a href="../../about/license/">License</a>
 </li>

diff --git a/docs/user_guide/installation/index.html b/docs/user_guide/installation/index.html
@@ -100,12 +100,6 @@
 
 
 
-<li >
-    <a href="../../about/contributing/">Contributing</a>
-</li>
-
-
-
 <li >
     <a href="../../about/license/">License</a>
 </li>