update doc

.gitignore

@@ -9,4 +9,5 @@ __pycache__/
 /no_git
 /build
 /dist
-/*.egg-info
+/*.egg-info
+/docs/_build

README.rst

@@ -0,0 +1,137 @@
+PyWebIO
+==================
+
+PyWebIO是一个用于在浏览器上获取输入和进行输出的工具库。能够将原有的通过终端交互的脚本快速服务化，供其他人在网络上通过浏览器访问使用；PyWebIO还可以方便地整合进现有的Web服务，非常适合于构建对UI要求不高的后端服务。
+
+特点：
+
+- 使用同步而不是基于回调的方式获取输入，无需在各个步骤之间保存状态，使用更方便
+- 代码侵入性小，对于旧脚本代码仅需修改输入输出逻辑
+- 支持多用户与并发请求
+- 支持整合到现有的Web服务，目前支持与Tornado和Flask的集成
+- 同时支持基于线程的执行模型和基于协程的执行模型
+
+Install
+------------
+
+.. code-block:: bash
+
+    pip3 install pywebio
+
+Quick start
+------------
+
+假设你编写了如下脚本来计算 `BMI指数 <https://en.wikipedia.org/wiki/Body_mass_index>`_ ：
+
+.. code-block:: python
+
+    # BMI.py
+    def bmi():
+        height = input("请输入你的身高(cm)：")
+        weight = input("请输入你的体重(kg)：")
+
+        BMI = float(weight) / (float(height) / 100) ** 2
+
+        top_status = [(14.9, '极瘦'), (18.4, '偏瘦'),
+                      (22.9, '正常'), (27.5, '过重'),
+                      (40.0, '肥胖'), (float('inf'), '非常肥胖')]
+
+        for top, status in top_status:
+            if BMI <= top:
+                print('你的 BMI 值: %.1f，身体状态：%s' % (BMI, status))
+                break
+
+    if __name__ == '__main__':
+        bmi()
+
+**在浏览器中进行输入输出**
+
+仅仅需将输入、输出函数替换成PyWebIO的输入输出函数就完成了改造(下面代码通过注释标出了改动部分)
+
+.. code-block:: python
+
+    # BMI.py
+    from pywebio.input import input  # Change 1
+    from pywebio.output import put_text  # Change 1
+
+    def bmi():
+        height = input("请输入你的身高(cm)：")  # Change 2
+        weight = input("请输入你的体重(kg)：")  # Change 2
+
+        BMI = float(weight) / (float(height) / 100) ** 2
+
+        top_status = [(14.9, '极瘦'), (18.4, '偏瘦'),
+                      (22.9, '正常'), (27.5, '过重'),
+                      (40.0, '肥胖'), (float('inf'), '非常肥胖')]
+
+        for top, status in top_status:
+            if BMI <= top:
+                put_text('你的 BMI 值: %.1f，身体状态：%s' % (BMI, status))  # Change 3
+                break
+
+    if __name__ == '__main__':
+        bmi()
+
+运行代码就可以在自动弹出的浏览器中与代码交互了：
+
+.. image:: /docs/assets/demo.gif
+
+**向外提供服务**
+
+上文对使用PyWebIO进行改造的程序，运行模式还是脚本，程序计算完毕后立刻退出。可以使用 ``pywebio.start_server`` 将程序功能作为Web服务提供：
+
+.. code-block:: python
+
+    # BMI.py
+    from pywebio import start_server
+    from pywebio.input import input
+    from pywebio.output import put_text
+
+    def bmi():
+        height = input("请输入你的身高(cm)：")
+        weight = input("请输入你的体重(kg)：")
+
+        BMI = float(weight) / (float(height) / 100) ** 2
+
+        top_status = [(14.9, '极瘦'), (18.4, '偏瘦'),
+                      (22.9, '正常'), (27.5, '过重'),
+                      (40.0, '肥胖'), (float('inf'), '非常肥胖')]
+
+        for top, status in top_status:
+            if BMI <= top:
+                put_text('你的 BMI 值: %.1f，身体状态：%s' % (BMI, status))
+                break
+
+    if __name__ == '__main__':
+        start_server(bmi)
+
+**与现有Web框架整合**
+
+仅需在现有的Tornado应用中加入加入两个 ``RequestHandler`` ，就可以将使用PyWebIO编写的函数整合进 ``Tornado`` 应用中了
+
+.. code-block:: python
+
+    import tornado.ioloop
+    import tornado.web
+    from pywebio.platform.tornado import webio_handler
+    from pywebio import STATIC_PATH
+
+    class MainHandler(tornado.web.RequestHandler):
+        def get(self):
+            self.write("Hello, world")
+
+    if __name__ == "__main__":
+        application = tornado.web.Application([
+            (r"/", MainHandler),
+            (r"/bmi/io", webio_handler(bmi)),  # bmi 即为上文中使用`PyWebIO`进行改造的函数
+            (r"/bmi/(.*)", tornado.web.StaticFileHandler, {"path": STATIC_PATH, 'default_filename': 'index.html'})
+        ])
+        application.listen(port=80, address='localhost')
+        tornado.ioloop.IOLoop.current().start()
+
+在 ``http://localhost/bmi/`` 页面上就可以计算BMI了
+
+文档
+------------
+
+使用手册和开发文档见 `https://pywebio.readthedocs.io <https://pywebio.readthedocs.io>`_

docs/guide.rst

@@ -382,16 +382,17 @@ PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务
 
     start_server(main, auto_open_webbrowser=True)
 
-与基于线程的会话类似，在基于协程的会话中，当任务函数和在会话内通过 ``run_async()`` 运行的携程全部结束后，会话关闭。
+`run_async(coro) <pywebio.session.run_async>` 返回一个 `TaskHandle <pywebio.session.coroutinebased.TaskHandle>` ，通过 ``TaskHandle`` 你可以查询协程运行状态和关闭协程。
+与基于线程的会话类似，在基于协程的会话中，当任务函数和在会话内通过 ``run_async()`` 运行的协程全部结束后，会话关闭。
 
 .. note::
 
    在基于协程的会话中， :doc:`pywebio.input </input>` 模块中的输入函数都需要使用 ``await`` 语法来获取返回值，
-   忘记使用 ``await`` 将会是你在使用基于协程的会话常常犯的错误。
+   忘记使用 ``await`` 将会是在使用基于协程的会话常常犯的错误。
 
 与Web框架进行集成
 """""""""""""""""""""
-基于协程的会话同样可以与Web框架进行集成，只需要在原来传入任务函数的地方改为传入携程函数即可。
+基于协程的会话同样可以与Web框架进行集成，只需要在原来传入任务函数的地方改为传入协程函数即可。
 
 但当前在使用基于协程的会话集成进Flask时，存在一些限制：
 

docs/index.rst

@@ -1,9 +1,9 @@
 PyWebIO
 ==========
-PyWebIO是一个用于在浏览器上获取输入和进行输出的工具库。通过浏览器来提供更多输入输出方式，你可以将原有的通过终端交互的脚本快速服务化，供其他人在网络上通过浏览器访问使用；PyWebIO还可以方便地整合进现有的Web服务，非常适合于构建对UI要求不高的后端服务。
+PyWebIO是一个用于在浏览器上获取输入和进行输出的工具库。可以将原有的通过终端交互的脚本快速服务化，供其他人在网络上通过浏览器访问使用；PyWebIO还可以方便地整合进现有的Web服务，非常适合于构建对UI要求不高的后端服务。
 
 
-特点：
+特点
 ------------
 
 - 使用同步而不是基于回调的方式获取输入，无需在各个步骤之间保存状态，使用更方便
@@ -51,9 +51,7 @@ Hello, world
    if __name__ == '__main__':
        bmi()
 
-如果不是程序开始的头文件，你甚至不会意识到自己正在使用一个输入输出库。
-
-运行以上代码就可以在自动弹出的浏览器中与代码交互了：
+如果没有使用PywWebIO，这只是一个非常简单的脚本，而通过使用PywWebIO提供的输入输出函数，你可以在浏览器中与代码进行交互：
 
 .. image:: /assets/demo.*
 

pywebio/session/__init__.py

@@ -2,6 +2,8 @@
 .. autofunction:: run_async
 .. autofunction:: run_asyncio_coroutine
 .. autofunction:: register_thread
+.. autoclass:: pywebio.session.coroutinebased.TaskHandle
+   :members:
 """
 
 import asyncio

pywebio/session/coroutinebased.py

@@ -211,13 +211,14 @@ async def run_asyncio_coroutine(self, coro_obj):
 
 
 class TaskHandle:
+    """协程任务句柄"""
 
     def __init__(self, close, closed):
         self._close = close
         self._closed = closed
 
     def close(self):
-        """关闭任务"""
+        """关闭协程任务"""
         return self._close()
 
     def closed(self):