doc: update

pywebio/output.py

@@ -205,10 +205,12 @@ def put_text(text, inline=False, scope=Scope.Current, position=OutputPosition.BO
 
     :param any text: 文本内容
     :param bool inline: 文本行末不换行。默认换行
-    :param int/str scope: 内容输出的目标scope, 若scope不存在，则不进行任何输出操作。
-       `scope` 可以直接指定目标Scope名，或者使用int通过索引Scope栈来确定Scope：0表示最顶层也就是ROOT Scope，-1表示当前Scope，-2表示当前Scope的父Scope，...
+    :param int/str scope: 内容输出的目标scope，若scope不存在，则不进行任何输出操作。
+
+       可以直接指定目标Scope名，或者使用int通过索引Scope栈来确定Scope：0表示最顶层也就是ROOT Scope，-1表示当前Scope，-2表示进入当前Scope的前一个Scope，...
     :param int position: 在scope中输出的位置。
-       position为非负数时表示输出到scope的第position个(从0计数)子元素的前面；position为负数时表示输出到scope的倒数第position个(从-1计数)元素之后。
+
+       position>=0时表示输出到scope的第position个(从0计数)子元素的前面；position<0时表示输出到scope的倒数第position个(从-1计数)元素之后。
 
     参数 `scope` 和 `position` 的更多使用说明参见 :ref:`用户手册 <scope_param>`
     """
@@ -729,7 +731,7 @@ def put_widget(template, data, scope=Scope.Current, position=OutputPosition.BOTT
     :param template: html模版，使用 `mustache.js <https://github.com/janl/mustache.js>`_ 语法
     :param dict data:  渲染模版使用的数据.
 
-       数据可以包含输出函数( ``put_xxx()`` )的返回值, 可以使用 ``pywebio_output_parse`` 函数来解析 ``put_xxx()`` 内容.
+       数据可以包含输出函数( ``put_xxx()`` )的返回值, 可以使用 ``pywebio_output_parse`` 函数来解析 ``put_xxx()`` 内容；对于字符串输入， ``pywebio_output_parse`` 会将解析成html.
 
        ⚠️：使用 ``pywebio_output_parse`` 函数时，需要关闭mustache的html转义: ``{{& pywebio_output_parse}}`` , 参见下文示例.
     :param int scope, position: 与 `put_text` 函数的同名参数含义一致

pywebio/platform/__init__.py

@@ -1,6 +1,8 @@
 r"""
 ``platform`` 模块为PyWebIO提供了对不同Web框架的支持。
 
+具体用法参见用户手册 :ref:`与Web框架集成 <integration_web_framework>` 小节
+
 Tornado相关
 --------------
 .. autofunction:: start_server

pywebio/platform/aiohttp.py

@@ -105,7 +105,7 @@ def webio_handler(applications, allowed_origins=None, check_origin=None, websock
     """获取在aiohttp中运行PyWebIO任务函数的 `Request Handle <https://docs.aiohttp.org/en/stable/web_quickstart.html#aiohttp-web-handler>`_ 协程。
     Request Handle基于WebSocket协议与浏览器进行通讯。
 
-    :param list/dict/callable applications: PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。
+    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
         来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
 
@@ -160,7 +160,7 @@ def start_server(applications, port=0, host='', debug=False,
                  **aiohttp_settings):
     """启动一个 aiohttp server 将PyWebIO应用作为Web服务提供。
 
-    :param list/dict/callable applications: PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。
+    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
     :param int port: server bind port. set ``0`` to find a free port number to use
     :param str host: server bind host. ``host`` may be either an IP address or hostname.  If it's a hostname,

pywebio/platform/django.py

@@ -78,7 +78,7 @@ def webio_view(applications,
     """获取在django中运行PyWebIO任务的视图函数。
     基于http请求与前端进行通讯
 
-    :param list/dict/callable applications: PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。
+    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
     :param int session_expire_seconds: 会话不活跃过期时间。
     :param int session_cleanup_interval: 会话清理间隔。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
@@ -120,7 +120,7 @@ def start_server(applications, port=8080, host='localhost',
                  debug=False, **django_options):
     """启动一个 Django server 将PyWebIO应用作为Web服务提供。
 
-    :param list/dict/callable applications: PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。
+    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
     :param int port: server bind port. set ``0`` to find a free port number to use
     :param str host: server bind host. ``host`` may be either an IP address or hostname.
        set empty string or `None` to listen on all available interfaces.

pywebio/platform/flask.py

@@ -83,7 +83,7 @@ def webio_view(applications,
                allowed_origins=None, check_origin=None):
     """获取在Flask中运行PyWebIO任务的视图函数。基于http请求与前端进行通讯
 
-    :param list/dict/callable applications: PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。
+    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
     :param int session_expire_seconds: 会话不活跃过期时间。
     :param int session_cleanup_interval: 会话清理间隔。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
@@ -121,7 +121,7 @@ def start_server(applications, port=8080, host='localhost',
                  debug=False, **flask_options):
     """启动一个 Flask server 将PyWebIO应用作为Web服务提供。
 
-    :param list/dict/callable applications: PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。
+    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
     :param int port: server bind port. set ``0`` to find a free port number to use
     :param str host: server bind host. ``host`` may be either an IP address or hostname.
        set empty string or `None` to listen on all available interfaces.

pywebio/platform/tornado.py

@@ -116,7 +116,7 @@ def _webio_handler(applications, check_origin_func=_is_same_site):
 def webio_handler(applications, allowed_origins=None, check_origin=None):
     """获取在Tornado中运行PyWebIO任务的RequestHandle类。RequestHandle类基于WebSocket协议与浏览器进行通讯。
 
-    :param callable/list/dict applications: PyWebIO应用
+    :param callable/list/dict applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
         来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
 
@@ -177,10 +177,9 @@ def start_server(applications, port=0, host='', debug=False,
 
     :param list/dict/callable applications: PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。
 
-       类型为字典时，字典键为任务名，可以通过 ``app`` URL参数选择要运行的任务函数，默认使用运行 ``index`` 任务函数，
-       当 ``index`` 键不存在时，PyWebIO会提供一个默认的索引页作为主页。
+       类型为字典时，字典键为任务名，类型为列表时，函数名为任务名。
 
-       类型为列表时，函数名为任务名
+       可以通过 ``app`` URL参数选择要运行的任务，默认使用运行 ``index`` 任务函数，当 ``index`` 任务不存在时，PyWebIO会提供一个默认的索引页作为主页。
 
        任务函数为协程函数时，使用 :ref:`基于协程的会话实现 <coroutine_based_session>` ；任务函数为普通函数时，使用基于线程的会话实现。
     :param int port: server bind port. set ``0`` to find a free port number to use