doc: update demos docs

demos/__init__.py

@@ -1,5 +1,4 @@
-r"""示例
-
+r"""
 .. automodule:: demos.bmi
 .. automodule:: demos.input_usage
 .. automodule:: demos.output_usage

demos/__main__.py

@@ -5,6 +5,7 @@ from demos.bmi import main as bmi
 from demos.chat_room import main as chat_room
 from demos.input_usage import main as input_usage
 from demos.output_usage import main as output_usage
+from demos.config import charts_demo_host
 
 from pywebio import STATIC_PATH
 from pywebio.output import put_markdown, set_auto_scroll_bottom
@@ -22,9 +23,9 @@ index_md = r"""# PyWebIO demos
 ### 数据可视化demo
 PyWebIO还支持使用第三方库进行数据可视化
 
- - 使用`pyecharts`创建基于Echarts的图表 [**demos**](http://pywebio-charts.wangweimin.site/?pywebio_api=pyecharts)
- - 使用`cutecharts.py`创建卡通风格图表 [**demos**](http://pywebio-charts.wangweimin.site/?pywebio_api=cutecharts)
- - 使用`plotly`进行数据可视化 [**demos**](http://pywebio-charts.wangweimin.site/?pywebio_api=plotly)
+ - 使用`pyecharts`创建基于Echarts的图表 [**demos**]({charts_demo_host}/?pywebio_api=pyecharts)
+ - 使用`cutecharts.py`创建卡通风格图表 [**demos**]({charts_demo_host}/?pywebio_api=cutecharts)
+ - 使用`plotly`进行数据可视化 [**demos**]({charts_demo_host}/?pywebio_api=plotly)
 
 **数据可视化demo截图**
 
@@ -38,7 +39,7 @@ PyWebIO还支持使用第三方库进行数据可视化
 * PyWebIO Github [github.com/wang0618/PyWebIO](https://github.com/wang0618/PyWebIO)
 * 使用手册和实现文档见 [pywebio.readthedocs.io](https://pywebio.readthedocs.io)
 
-"""
+""".format(charts_demo_host=charts_demo_host)
 
 
 def index():

demos/bmi.py

@@ -4,7 +4,7 @@ BMI指数计算
 
 计算 `BMI指数 <https://en.wikipedia.org/wiki/Body_mass_index>`_ 的简单应用
 
-`Demo地址 <https://pywebio.herokuapp.com/?pywebio_api=bmi>`_  `源码 <https://github.com/wang0618/PyWebIO/blob/master/demos/bmi.py>`_
+:demo_host:`Demo地址 </?pywebio_api=bmi>`  `源码 <https://github.com/wang0618/PyWebIO/blob/master/demos/bmi.py>`_
 """
 from pywebio import start_server
 from pywebio.input import *

demos/chat_room.py

@@ -3,7 +3,7 @@
 ^^^^^^^^^^^
 和当前所有在线的人聊天
 
-`Demo地址 <https://pywebio.herokuapp.com/?pywebio_api=chat_room>`_  `源码 <https://github.com/wang0618/PyWebIO/blob/master/demos/chat_room.py>`_
+:demo_host:`Demo地址 </?pywebio_api=chat_room>`  `源码 <https://github.com/wang0618/PyWebIO/blob/master/demos/chat_room.py>`_
 
 * 使用基于协程的会话
 * 使用 `run_async() <pywebio.session.run_async>` 启动后台协程

demos/config.py

@@ -0,0 +1,5 @@
+# demos 模块的部署地址
+demo_host = 'http://pywebio-demos.wangweimin.site'
+
+# https://github.com/wang0618/pywebio-chart-gallery 的部署地址
+charts_demo_host = 'http://pywebio-charts.wangweimin.site'

demos/input_usage.py

@@ -3,7 +3,7 @@
 ^^^^^^^^^^^
 演示PyWebIO支持的各种输入形式
 
-`Demo地址 <https://pywebio.herokuapp.com/?pywebio_api=input_usage>`_  `源码 <https://github.com/wang0618/PyWebIO/blob/master/demos/input_usage.py>`_
+:demo_host:`Demo地址 </?pywebio_api=input_usage>`  `源码 <https://github.com/wang0618/PyWebIO/blob/master/demos/input_usage.py>`_
 """
 from pywebio import start_server
 from pywebio.input import *

demos/output_usage.py

@@ -3,7 +3,7 @@
 ^^^^^^^^^^^
 演示PyWebIO支持的各种输出形式
 
-`Demo地址 <https://pywebio.herokuapp.com/?pywebio_api=output_usage>`_  `源码 <https://github.com/wang0618/PyWebIO/blob/master/demos/output_usage.py>`_
+:demo_host:`Demo地址 </?pywebio_api=output_usage>`  `源码 <https://github.com/wang0618/PyWebIO/blob/master/demos/output_usage.py>`_
 """
 from pywebio import start_server
 from pywebio.output import *

docs/conf.py

@@ -71,6 +71,12 @@ def setup(app):
 
 
 # -- Extension configuration -------------------------------------------------
+from demos import config
+
+extlinks = {
+    'demo_host': (config.demo_host + '%s', 'demo_host'),
+    'charts_demo_host': (config.charts_demo_host + '%s', 'charts_demo_host')
+}
 
 from sphinx.builders.html import StandaloneHTMLBuilder
 

docs/demos.rst

@@ -1,4 +1,12 @@
 Demos
 ==========
 
-.. automodule:: demos
+基本demo
+------------
+使用PyWebIO编写的示例应用
+
+.. automodule:: demos
+
+数据可视化demo
+-----------------
+PyWebIO支持使用第三方库进行数据可视化，详情见 :ref:`使用PyWebIO进行数据可视化 <visualization>`

docs/index.rst

@@ -80,6 +80,7 @@ Documentation
    session
    platform
    misc
+   libraries_support
    demos
 
 .. toctree::

docs/libraries_support.rst

@@ -0,0 +1,50 @@
+第三方库生态
+==============
+
+.. _visualization:
+
+数据可视化
+-------------
+PyWebIO支持使用第三方库进行数据可视化
+
+pyecharts
+^^^^^^^^^^^^^^^^^^^^^^
+`pyecharts <https://github.com/pyecharts/pyecharts>`_ 是一个使用Python创建 `Echarts <https://github.com/ecomfe/echarts>`_ 可视化图表的库。
+
+在 PyWebIO 中使用 `put_html() <pywebio.output.put_html>` 可以输出 pyecharts 库创建的图表::
+
+    # chart 为 pyecharts 的图表实例
+    pywebio.output.put_html(chart.render_notebook())
+
+相应demo见 :charts_demo_host:`pyecharts demo </?pywebio_api=pyecharts>`
+
+.. image:: https://cdn.jsdelivr.net/gh/wang0618/pywebio-chart-gallery@master/assets/pyecharts.gif
+
+plotly
+^^^^^^^^^^^^^^^^^^^^^^
+`plotly.py <https://github.com/plotly/plotly.py>`_ 是一个非常流行的Python数据可视化库，可以生成高质量的交互式图表。
+
+PyWebIO 支持输出使用 plotly 库创建的图表。使用方式为在PyWebIO会话中调用::
+
+    # fig 为 plotly 的图表实例
+    html = fig.to_html(include_plotlyjs="require", full_html=False)
+    pywebio.output.put_html(html)
+
+相应demo见 :charts_demo_host:`plotly demo </?pywebio_api=plotly>`
+
+.. image:: https://cdn.jsdelivr.net/gh/wang0618/pywebio-chart-gallery@master/assets/plotly.png
+
+cutecharts.py
+^^^^^^^^^^^^^^^^^^^^^^
+
+`cutecharts.py <https://github.com/cutecharts/cutecharts.py>`_ 是一个可以创建具有卡通风格的可视化图表的python库。
+底层使用了 `chart.xkcd <https://github.com/timqian/chart.xkcd>`_ Javascript库。
+
+在 PyWebIO 中使用 `put_html() <pywebio.output.put_html>` 可以输出 cutecharts.py 库创建的图表::
+
+    # chart 为 cutecharts 的图表实例
+    pywebio.output.put_html(chart.render_notebook())
+
+相应demo见 :charts_demo_host:`cutecharts demo </?pywebio_api=cutecharts>`
+
+.. image:: https://cdn.jsdelivr.net/gh/wang0618/pywebio-chart-gallery@master/assets/cutecharts.png

pywebio/output.py

@@ -164,7 +164,7 @@ def put_html(html, anchor=None, before=None, after=None):
     """
     输出Html内容。
 
-    与支持通过Html输出内容到 `Jupyter Notebook <https://nbviewer.jupyter.org/github/ipython/ipython/blob/master/examples/IPython%20Kernel/Rich%20Output.ipynb#HTML>` 的库兼容。
+    与支持通过Html输出内容到 `Jupyter Notebook <https://nbviewer.jupyter.org/github/ipython/ipython/blob/master/examples/IPython%20Kernel/Rich%20Output.ipynb#HTML>`_ 的库兼容。
 
     :param html: html字符串或 实现了 `IPython.display.HTML` 接口的类的实例
     :param str anchor, before, after: 与 `put_text` 函数的同名参数含义一致