doc: use sphinx-tabs

.readthedocs.yml

@@ -24,4 +24,4 @@ python:
     - method: pip
       path: .
       extra_requirements:
-        - flask
+        - all

docs/conf.py

@@ -30,6 +30,8 @@ extensions = [
     'sphinx.ext.autodoc',
     # "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    'sphinx_tabs.tabs',
+    'sphinx.ext.extlinks'
 ]
 
 primary_domain = "py"
@@ -57,6 +59,17 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 #
 html_theme = "sphinx_rtd_theme"
 
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['static']
+
+
+def setup(app):
+    """Configure Sphinx"""
+    app.add_stylesheet('pywebio.css')
+
+
 # -- Extension configuration -------------------------------------------------
 
 from sphinx.builders.html import StandaloneHTMLBuilder

docs/guide.rst

@@ -270,61 +270,62 @@ Server mode 下，由于对多会话的支持，如果需要在新创建的线
 
 PyWebIO 目前支持与Flask和Tornado Web框架的集成。
 与Web框架集成需要完成两件事情：托管PyWebIO静态文件；暴露PyWebIO后端接口。
-这其中需要注意静态文件和后端接口的路径约定，以及静态文件与后端接口分开部署时因为跨域而需要的特别设置。
+这其中需要注意前端页面和后端接口的路径约定，以及前端静态文件与后端接口分开部署时因为跨域而需要的特别设置。
 
-与Tornado集成
-^^^^^^^^^^^^^^^^
+不同Web框架的集成方法如下：
 
-要将使用PyWebIO编写的任务函数集成进Tornado应用，需要在Tornado应用中引入两个 ``RequestHandler`` ,
-一个 ``RequestHandler`` 用来提供静态的前端文件，另一个 ``RequestHandler`` 用来和浏览器进行WebSocket通讯::
+.. tabs::
 
-    import tornado.ioloop
-    import tornado.web
-    from pywebio.platform.tornado import webio_handler
-    from pywebio import STATIC_PATH
+   .. tab:: Tornado
 
-    class MainHandler(tornado.web.RequestHandler):
-        def get(self):
-            self.write("Hello, world")
+        需要在Tornado应用中引入两个 ``RequestHandler`` ,
+        一个 ``RequestHandler`` 用来提供静态的前端文件，另一个 ``RequestHandler`` 用来和浏览器进行WebSocket通讯::
 
-    if __name__ == "__main__":
-        application = tornado.web.Application([
-            (r"/", MainHandler),
-            (r"/tool/io", webio_handler(task_func)),  # task_func 为使用PyWebIO编写的任务函数
-            (r"/tool/(.*)", tornado.web.StaticFileHandler,
-                  {"path": STATIC_PATH, 'default_filename': 'index.html'})
-        ])
-        application.listen(port=80, address='localhost')
-        tornado.ioloop.IOLoop.current().start()
+            import tornado.ioloop
+            import tornado.web
+            from pywebio.platform.tornado import webio_handler
+            from pywebio import STATIC_PATH
 
-以上代码调用 `webio_handler(task_func) <pywebio.platform.webio_handler>` 来获得PyWebIO和浏览器进行通讯的Tornado ``RequestHandler`` ，
-并将其绑定在 ``/tool/io`` 路径下；同时将PyWebIO的静态文件使用 ``tornado.web.StaticFileHandler`` 托管到 ``/tool/(.*)`` 路径下。
-启动Tornado服务后，访问 ``http://localhost/tool/`` 即可使用PyWebIO服务
+            class MainHandler(tornado.web.RequestHandler):
+                def get(self):
+                    self.write("Hello, world")
 
-.. note::
+            if __name__ == "__main__":
+                application = tornado.web.Application([
+                    (r"/", MainHandler),
+                    (r"/tool/io", webio_handler(task_func)),  # task_func 为使用PyWebIO编写的任务函数
+                    (r"/tool/(.*)", tornado.web.StaticFileHandler,
+                          {"path": STATIC_PATH, 'default_filename': 'index.html'})
+                ])
+                application.listen(port=80, address='localhost')
+                tornado.ioloop.IOLoop.current().start()
 
-   在Tornado中，PyWebIO使用WebSocket协议和浏览器进行通讯，所以，如果你的Tornado应用处在反向代理(比如Nginx)之后，
-   可能需要特别配置反向代理来支持WebSocket协议，:ref:`这里 <nginx_ws_config>` 有一个Nginx配置WebSocket的例子。
+        以上代码调用 `webio_handler(task_func) <pywebio.platform.tornado.webio_handler>` 来获得PyWebIO和浏览器进行通讯的Tornado ``RequestHandler`` ，
+        并将其绑定在 ``/tool/io`` 路径下；同时将PyWebIO的静态文件使用 ``tornado.web.StaticFileHandler`` 托管到 ``/tool/(.*)`` 路径下。
+        启动Tornado服务后，访问 ``http://localhost/tool/`` 即可使用PyWebIO服务
 
+        .. note::
 
-与Flask集成
-^^^^^^^^^^^^^^^^
+           在Tornado中，PyWebIO使用WebSocket协议和浏览器进行通讯，所以，如果你的Tornado应用处在反向代理(比如Nginx)之后，
+           可能需要特别配置反向代理来支持WebSocket协议，:ref:`这里 <nginx_ws_config>` 有一个Nginx配置WebSocket的例子。
 
-和集成到Tornado相似，在与Flask集成的集成中，你也需要添加两个PyWebIO相关的路由：一个用来提供静态的前端文件，另一个用来和浏览器进行Http通讯::
+   .. tab:: Flask
 
-    from pywebio.platform.flask import webio_view
-    from pywebio import STATIC_PATH
-    from flask import Flask, send_from_directory
+        需要添加两个PyWebIO相关的路由：一个用来提供静态的前端文件，另一个用来和浏览器进行Http通讯::
 
-    app = Flask(__name__)
-    app.route('/io', methods=['GET', 'POST', 'OPTIONS'])(webio_view(task_func))
+            from pywebio.platform.flask import webio_view
+            from pywebio import STATIC_PATH
+            from flask import Flask, send_from_directory
 
-    @app.route('/')
-    @app.route('/<path:static_file>')
-    def serve_static_file(static_file='index.html'):
-        return send_from_directory(STATIC_PATH, static_file)
+            app = Flask(__name__)
+            app.route('/io', methods=['GET', 'POST', 'OPTIONS'])(webio_view(task_func))
+
+            @app.route('/')
+            @app.route('/<path:static_file>')
+            def serve_static_file(static_file='index.html'):
+                return send_from_directory(STATIC_PATH, static_file)
 
-    app.run(host='localhost', port=80)
+            app.run(host='localhost', port=80)
 
 
 .. _integration_web_framework_note:
@@ -347,7 +348,7 @@ PyWebIO默认通过当前页面的同级的 ``./io`` API与后端进行通讯，
    指定其他服务器需要使用完整格式: ``ws://example.com:8080/aaa/io`` ,或者省略协议字段: ``//example.com:8080/aaa/io`` 。
    省略协议字段时，PyWebIO根据当前页面的协议确定要使用的协议: 若当前页面为http协议，则后端接口为ws协议；若当前页面为https协议，则后端接口为wss协议；
 
-   当后端API与当前页面不再同一host下时，需要在 `webio_handler() <pywebio.platform.webio_handler>` 或
+   当后端API与当前页面不再同一host下时，需要在 `webio_handler() <pywebio.platform.tornado.webio_handler>` 或
    `webio_view() <pywebio.platform.flask.webio_view>` 中使用 ``allowed_origins`` 或 ``check_origin``
    参数来允许后端接收页面所在的host
 

docs/static/pywebio.css

@@ -0,0 +1,18 @@
+/* Tabs */
+
+.ui.menu {
+    font-family: Helvetica;
+    min-height: 0;
+}
+
+.ui.tabular.menu .item {
+    padding: .25em 1em;
+}
+
+.ui.menu .item {
+    padding: 0;
+}
+
+.sphinx-tabs {
+    margin-bottom: 1em;
+}

setup.py

@@ -1,4 +1,5 @@
 import os
+from functools import reduce
 
 from setuptools import setup, find_packages
 
@@ -11,6 +12,18 @@ with open(os.path.join(here, 'pywebio', '__version__.py')) as f:
 with open('README.md') as f:
     readme = f.read()
 
+extras_require = {
+    'flask': ['flask'],
+    'dev': [
+        'selenium==3.*',
+        'percy-python-selenium',
+        'coverage',
+        'sphinx-tabs'
+    ]
+}
+# 可以使用 pip install pywebio[all] 安装所有额外依赖
+extras_require['all'] = reduce(lambda x, y: x + y, extras_require.values())
+
 setup(
     name=about['__package__'],
     version=about['__version__'],
@@ -68,14 +81,7 @@ setup(
     install_requires=[
         'tornado>=4.3.0',  # After this version, the new async/await keywords in Python 3.5 are supported
     ],
-    extras_require={
-        'flask': ['flask'],
-        'dev': [
-            'selenium==3.*',
-            'percy-python-selenium',
-            'coverage',
-        ]
-    },
+    extras_require=extras_require,
     project_urls={
         'Documentation': 'https://pywebio.readthedocs.io',
         'Source': 'https://github.com/wang0618/PyWebIO',