doc: add FAQ, update doc

docs/FAQ.rst

@@ -0,0 +1,21 @@
+常见问题
+==========================
+
+.. contents::
+   :local:
+
+如何让输入框在提交后不消失，并可以持续性地输入
+----------------------------------------------------------
+PyWebIO 的设计就是输入表单在成功提交后就销毁，因为 PyWebIO 的输入是阻塞式的，一旦提交表单，输入函数就返回了，此时表单还留在界面上是没有意义的。如果想实现持续性的输入，可以将接收输入以及后续操作放到一个 ``while`` 循环中。
+
+
+如何输出一个诸如搜索栏的输入框
+----------------------------------------------------------
+很遗憾，PyWebIO并不支持将输入框作为一般性的内容输出到页面。因为这样就相当于又回到了基于回调获取输入的方式了，会导致应用开发的复杂性提高，PyWebIO不太推荐过多依赖回调机制，所以对此仅提供了非常少的支持。
+不过也可以使用另一种方式实现近似的效果：只需要在需要显示输入框的地方放置一个button( `put_buttons() <pywebio.output.put_buttons>` )，然后在button的回调函数中调用输入函数来获取输入并进行后续操作。
+
+
+为什么 ``put_buttons()`` 的回调不起作用
+----------------------------------------------------------
+一般情况下，在Server模式下，任务函数一旦返回(或在Script模式下，脚本运行结束)，会话就结束了，此时事件回调也将不起作用，可以在任务函数(或脚本)末尾处使用 `pywebio.session.hold()` 函数来将会话保持，这样在用户关闭浏览器页面前，事件回调将一直可用。 参见 :ref:`Server模式与Script模式 <server_and_script_mode>`
+

docs/demos.rst

@@ -1,4 +1,4 @@
-Demos
+示例Demos
 ==========
 
 基本demo

docs/guide.rst

@@ -840,6 +840,7 @@ PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务
 除了基于线程的会话，PyWebIO还提供了基于协程的会话。基于协程的会话接受协程函数作为任务函数。
 
 基于协程的会话为单线程模型，所有会话都运行在一个线程内。对于IO密集型的任务，协程比线程占用更少的资源同时又拥有媲美于线程的性能。
+另外，协程的上下文切换具有可预测性，能够减少程序同步与加锁的需要，可以有效避免大多数临界区问题。
 
 使用协程会话
 ^^^^^^^^^^^^^^^^
@@ -974,4 +975,16 @@ PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务
     threading.Thread(target=run_event_loop, daemon=True).start()
     app.run(host='localhost', port='80')
 
-最后，使用PyWebIO编写的协程函数不支持Script模式，总是需要使用 ``start_server`` 来启动一个服务或者集成进Web框架来调用。
+最后，使用PyWebIO编写的协程函数不支持Script模式，总是需要使用 ``start_server`` 来启动一个服务或者集成进Web框架来调用。
+
+
+Last but not least
+---------------------
+
+以上就是PyWebIO的全部功能了，你可以继续阅读接下来的文档，或者立即开始PyWebIO应用的编写了。
+
+最后再提供一条建议，当你在使用PyWebIO遇到设计上的问题时，可以问一下自己：如果在是在终端程序中我会怎么做？
+如果你已经有答案了，那么在PyWebIO中一样可以使用这样的方式完成。如果问题依然存在或者觉得解决方案不够好，
+你可以考虑使用 `put_buttons() <pywebio.output.put_buttons>` 提供的回调机制。
+
+好了，Have fun with PyWebIO!

docs/index.rst

@@ -88,6 +88,7 @@ Documentation
 .. toctree::
    :titlesonly:
 
+   FAQ
    releases
 
 .. toctree::

docs/input.rst

@@ -1,4 +1,4 @@
-``pywebio.input`` --- Get input from web browser
+``pywebio.input`` --- 输入模块
 ====================================================
 
 .. automodule:: pywebio.input

docs/misc.rst

@@ -1,4 +1,4 @@
-Other
+其他
 ============
 
 .. _codemirror_options:

docs/output.rst

@@ -1,4 +1,4 @@
-``pywebio.output`` --- Make output to web browser
+``pywebio.output`` --- 输出模块
 ====================================================
 
 .. automodule:: pywebio.output

docs/platform.rst

@@ -1,4 +1,4 @@
-``pywebio.platform`` --- Run and integrate with Web framework
+``pywebio.platform`` --- Web框架支持
 ===============================================================
 
 .. automodule:: pywebio.platform

docs/session.rst

@@ -1,4 +1,4 @@
-``pywebio.session`` --- More control to session
+``pywebio.session`` --- 会话相关
 ====================================================
 
 .. automodule:: pywebio.session

pywebio/output.py

@@ -605,6 +605,11 @@ def put_buttons(buttons, onclick, small=None, link_style=False, scope=Scope.Curr
             put_text("You click delete button")
 
         put_buttons(['edit', 'delete'], onclick=[edit, delete])
+
+    .. attention::
+
+        在PyWebIO会话(关于会话的概念见 :ref:`Server与script模式 <server_and_script_mode>` )结束后，事件回调也将不起作用，
+        可以在任务函数末尾处使用 `pywebio.session.hold()` 函数来将会话保持，这样在用户关闭浏览器页面前，事件回调将一直可用。
     """
     btns = _format_button(buttons)