Docs for v050 (pyecharts#506)

* 格式化 setup.py * Fix: pyecharts#504 修复 markpoint 标记点标注不显示的 bug * Update: changelog 文档更新 * Update: 文档更新 * Reformat: make white happy * Add: 新增 test_js_event.py 测试文件 * Update: 文档完善 * Update: changelog update * Update: api docs update * Update: DOCS UPDATE * Add: 新增 test_js_function.py 测试文件 * Add: 新增测试断言 * Update: fix borken test * Fix demo for translator docs * 📚 update the import location of Date * 💚 update test cases * Refactor translator docs * Update translator docs * Add technical_docs * Update: update translator.md * Update: update .gitgnore for vscode * Update: advanced.md update * Merge branch 'docs-for-v050' of github.com:chenjiandongx/pyecharts into docs-for-v050 # Conflicts: # docs/zh-cn/advanced.md # docs/zh-cn/translator.md * 📚 minor doc update * 👕 fix grammar
gzadigo · Apr 27, 2018 · ad2b2be · ad2b2be
1 parent 009b12e
commit ad2b2be
Show file tree

Hide file tree

Showing 21 changed files with 666 additions and 146 deletions.
diff --git a/.gitignore b/.gitignore
@@ -92,3 +92,6 @@ ENV/
 
 # for mac
 .DS_store
+
+# for vscode
+.vscode/
diff --git a/README.md b/README.md
@@ -82,7 +82,14 @@ It will create a file named *render.html* in the root directory, open file with
 
 [pyecharts-snapshot](https://github.com/pyecharts/pyecharts-snapshot) is [a command line utility](https://github.com/pyecharts/pyecharts-snapshot#usage) and [a library extension](https://github.com/pyecharts/pyecharts-snapshot#example-programs) which renders the output of pyecharts as a svg, png, jpeg, gif image or a pdf file.
 
-See more detail at that repositoty.
+After you will have installed pyecharts-snapshot, you can modify previous example file slightly and get png output directly:
+
+
+```python
+bar.render(path="render.png")
+```
+
+So please see installation instruction and other usage at that repositoty.
 
 ## Platform Support
 
@@ -100,15 +107,15 @@ In the case of online jshost mode, you can also download as some file formats (i
 
 ### Integrate With Web Framework
 
-With the help of pyecharts API,it is easy to integrate pyecharts to your web projects, such as Flask and Django.
+With the help of pyecharts API, it is easy to integrate pyecharts to your web projects, such as Flask and Django.
 
 Demo
 
 ![flask-0](https://user-images.githubusercontent.com/19553554/35081158-3faa7c34-fc4d-11e7-80c9-2de79371374f.gif)
 
 ## Advance Topics
 
-### Cusom Template FIles and Layout
+### Cusom Template Files and Layout
 
 pyecharts exposes engine API so that you can use your own template file and integrate with CSS framework.
 

diff --git a/docs/README.md b/docs/README.md
@@ -11,7 +11,7 @@ pyecharts 是一个用于生成 Echarts 图表的类库。Echarts 是百度开
 
 **高级话题**
 
-[图表 API](zh-cn/api) | [自定义地图](zh-cn/customize_map)
+[图表 API](zh-cn/api) | [自定义地图](zh-cn/customize_map) | [回调函数和事件处理](zh-cn/advanced) | [语言翻译扩展](zh-cn/translator)
 
 **平台支持**
 
@@ -21,6 +21,11 @@ pyecharts 是一个用于生成 Echarts 图表的类库。Echarts 是百度开
 
 [示例项目](https://github.com/pyecharts/pyecharts-users-cases) | [地理地图数据](zh-cn/datasets)
 
+**项目发布**
+
+[版本日志](zh-cn/changelog) | [发布日志](zh-cn/release-note/)
+
 **项目开发**
 
-[版本日志](zh-cn/changelog) | [发布日志](zh-cn/release-note/) | [开发团队](zh-cn/team) | [赞助者名单](zh-cn/donors)  | [FAQ](zh-cn/faq)
+[技术文档](zh-cn/technical_docs) |  [开发团队](zh-cn/team) | [赞助者名单](zh-cn/donors)  | [FAQ](zh-cn/faq)
+
diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md
@@ -11,7 +11,7 @@ pyecharts 是一个用于生成 Echarts 图表的类库。Echarts 是百度开
 
 **高级话题**
 
-[图表 API](zh-cn/api) | [自定义地图](zh-cn/customize_map)
+[图表 API](zh-cn/api) | [自定义地图](zh-cn/customize_map) | [回调函数和事件处理](zh-cn/advanced) | [语言翻译扩展](zh-cn/translator)
 
 **平台支持**
 
@@ -21,6 +21,11 @@ pyecharts 是一个用于生成 Echarts 图表的类库。Echarts 是百度开
 
 [示例项目](https://github.com/pyecharts/pyecharts-users-cases) | [地理地图数据](zh-cn/datasets)
 
+**项目发布**
+
+[版本日志](zh-cn/changelog) | [发布日志](zh-cn/release-note/)
+
 **项目开发**
 
-[版本日志](zh-cn/changelog) | [发布日志](zh-cn/release-note/) | [开发团队](zh-cn/team) | [FAQ](zh-cn/faq)
+[技术文档](zh-cn/technical_docs) |  [开发团队](zh-cn/team) | [赞助者名单](zh-cn/donors)  | [FAQ](zh-cn/faq)
+
diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md
@@ -1,5 +1,6 @@
 - [快速开始](zh-cn/prepare)
 - [图表详情](zh-cn/charts)
+- [高级用法](zh-cn/advanced)
 - [地图自定义](zh-cn/customize_map)
 - [pyecharts+Flask](zh-cn/flask)
 - [pyecharts+Django](zh-cn/django)

diff --git a/docs/zh-cn/advanced.md b/docs/zh-cn/advanced.md
@@ -0,0 +1,250 @@
+> 高级用法篇：本文档描述了 pyecharts 库的高级进阶用法。
+
+## 概述
+
+自 v0.5.0 开始， pyecharts 支持 *javascript 回调函数* 和 *echarts 事件处理函数* ，进一步覆盖 [ECharts](http://echarts.baidu.com/) 相关特性。为项目发展注入新的活力。
+
+在 Python-To-Javascript 语言翻译领域，[javascripthon](https://pypi.python.org/pypi/javascripthon)  是一个简单的 Python3.5+ 到 Javascript 的语言翻译器;  [dukpy](https://github.com/amol-/dukpy) 支持 Python2.7 和 Python 3.4 的语言翻译。
+
+基于以上事实，pyecharts 团队开发了  [pyecharts-javascripthon](https://github.com/pyecharts/pyecharts-javascripthon) 作为底层的 Python-To-Javascript 语言翻译库，封装了以上两个不同的翻译器，并提供若干个 Javascript 数据类型适配模块。
+
+pyecharts 目前仅使用了并封装一部分的 Javascripthon 的翻译规则，主要是 **函数翻译(Function Translate)** 。使用伪代码表示如下：
+
+```
+输入：一个 Python 的函数对象
+输出：一个多行的 unicode 字符串
+```
+
+比如能够将以下的 Python 函数：
+
+```
+def add(x, y):
+    return x + y
+```
+
+翻译为以下 Javascript 函数。
+
+```
+function add(x, y) {
+    return (x + y);
+}
+```
+
+对于 pyecharts 使用者来说，无需了解该翻译器具体的工作原理。
+
+## 安装
+
+### 基本安装
+
+pyecharts 默认已经安装了 pyecharts-javascripthon ，同时也可以通过 pip 安装。
+
+```
+$ pip install pyecharts-javascripthon 
+```
+
+### 环境限制
+
+由于 Javascripthon 要求 Python 的版本至少为 3.5+ 而 pyecharts 用户是 python 2.7, 3.4, 3.5 和 3.6, pyecharts-javascripthon 采用了双轨制：python 3.5+ 用户直接用 Javascripthon；python 2.7 和 3.4 的用户调用网络翻译服务 (software as a service)。同时，希望大家支持这个网络服务的运营费用。
+
+> 注意： Python2.7-3.4 的用户使用时请确保系统可以联网。
+
+
+## 使用 JavaScript 回调函数
+
+### 基本使用
+
+pyecharts 已经封装了底层相关逻辑，对使用者是透明的。因此你可以像之前一样的使用。将回函函数对象通过 `add` 方法赋值到 echarts 配置字典中，这里的回调函数需满足以下条件之一：
+
+- 使用 `def` 定义的命名函数
+
+注意的是目前暂不支持 `lambda` 表达式。
+
+例子：
+
+```python
+from pyecharts import Bar
+
+
+def label_formatter(params):
+    return params.value + ' [Good!]'
+
+
+attr = ["Jan", "Feb"]
+v1 = [2.0, 4.9]
+bar = Bar("Bar chart", "precipitation and evaporation one year")
+bar.add("precipitation", attr, v1, is_label_show=True, label_formatter=label_formatter)
+bar.render()
+
+```
+
+> 回调函数格式参考自  [series[i]-bar.label.formatter](http://echarts.baidu.com/option.html#series-bar.label.formatter) 。
+
+效果图
+
+![bar-label-formatter-callback](https://user-images.githubusercontent.com/9875406/38666230-07c1aa66-3e71-11e8-9e9f-43fb7d707a64.png)
+
+### Tooltip 示例
+
+举个例子，pyecharts 用户经常会提问 Geo 图中如何在 tooltip 中只显示地图坐标名称和数值，不显示经纬度。
+
+像这样
+
+```python
+def test_geo_shantou_city():
+    data = [('澄海区', 30), ('南澳县', 40), ('龙湖区', 50), ('金平区', 60)]
+    geo = Geo("汕头市地图示例", **style.init_style)
+    attr, value = geo.cast(data)
+    geo.add(
+        "",
+        attr,
+        value,
+        maptype="汕头",
+        is_visualmap=True,
+        is_legend_show=False,
+        label_emphasis_textsize=15,
+        label_emphasis_pos='right',
+    )
+    geo.render()
+```
+得到
+
+![](https://user-images.githubusercontent.com/19553554/39248236-186a50ae-48ce-11e8-84eb-e58ba17eca5c.png)
+
+而现在，你可以这么操作，先定义一个 `geo_formatter` 函数
+
+```python
+def geo_formatter(params):
+    return params.name + ' : ' + params.value[2]
+
+def test_geo_shantou_city():
+    data = [('澄海区', 30), ('南澳县', 40), ('龙湖区', 50), ('金平区', 60)]
+    geo = Geo("汕头市地图示例", **style.init_style)
+    attr, value = geo.cast(data)
+    geo.add(
+        "",
+        attr,
+        value,
+        maptype="汕头",
+        is_visualmap=True,
+        is_legend_show=False,
+        tooltip_formatter=geo_formatter,    # 重点在这里，将函数直接传递为参数。
+        label_emphasis_textsize=15,
+        label_emphasis_pos='right',
+    )
+    geo.render()
+```
+就可以看到下面的效果了。
+
+![](https://user-images.githubusercontent.com/19553554/39248244-1be6da4a-48ce-11e8-931f-059879c5dcf4.png)
+
+本新功能属于进阶用法，需要用户对 metapensiero.pj 和 Echarts 官方配置项有一定的了解。
+
+
+## 使用 JavaScript 事件处理函数
+
+Echarts 本身提供了 [api/events](http://echarts.baidu.com/api.html#events) 事件处理函数，主要通过 on 方式实现。
+
+pyecharts 根据官方提供的 events 列表，提供了如下全局事件名变量。位于 `pyecharts.echarts.events` 模块中。
+
+``` python
+# Mouse Events
+MOUSE_CLICK = "click"
+MOUSE_DBCLICK = "dbclick"
+MOUSE_DOWN = "mousedown"
+MOUSE_OVER = "mouseover"
+MOUSE_GLOBALOUT = "globalout"
+
+# Other Events
+LEGEND_SELECT_CHANGED = "legendselectchanged"
+LEGEND_SELECTED = "legendselected"
+LEGEND_UNSELECTAED = "legendunselected"
+LEGEND_SCROLL = "legendscroll"
+DATA_ZOOM = "datazoom"
+DATA_RANGE_SELECTED = "datarangeselected"
+TIMELINE_CHANGED = "timelinechanged"
+TIMELINE_PLAY_CHANGED = "timelineplaychanged"
+RESTORE = "restore"
+DATA_VIEW_CHANGED = "dataviewchanged"
+MAGIC_TYPE_CHANGED = "magictypechanged"
+GEO_SELECT_CHANGED = "geoselectchanged"
+GEO_SELECTED = "geoselected"
+GEO_UNSELECTED = "geounselected"
+PIE_SELECT_CHANGED = "pieselectchanged"
+PIE_SELECTED = "pieselected"
+PIE_UNSELECTED = "pieunselected"
+MAP_SELECT_CHANGED = "mapselectchanged"
+MAP_SELECTED = "mapselected"
+MAP_UNSELECTED = "mapunselected"
+AXIS_AREA_SELECTED = "axisareaselected"
+FOCUS_NODE_ADJACENCY = "focusnodeadjacency"
+UNFOCUS_NODE_ADJACENCY = "unfocusnodeadjacency"
+BRUSH = "brush"
+BRUSH_SELECTED = "brushselected"
+```
+
+使用方式如下，
+```python
+#!/usr/bin/env python
+# coding=utf-8
+from __future__ import unicode_literals
+
+import pyecharts.echarts.events as events
+from pyecharts import Bar
+from pyecharts_javascripthon.dom import alert
+
+
+def on_click():
+    alert("点击事件触发")
+
+
+def test_mouse_click():
+    bar = Bar("我的第一个图表", "这里是副标题")
+    bar.add(
+        "服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90]
+    )
+    bar.on(events.MOUSE_CLICK, on_click)
+    bar.render()
+```
+效果
+
+![](https://user-images.githubusercontent.com/19553554/39252189-b02b5420-48d7-11e8-9c53-6f0fb6d386c0.gif)
+
+## 注意
+
+第一，pyecharts 并不会检查 echarts 图表配置选项是否支持回调函数，关于这一部分可参考 ECharts 文档。
+
+这里指的是，options 参数本身是否支持回调函数，比如
+```python
+def my_title():
+    return 'my_title'
+bar.add(my_title, [], [])
+```
+在 pyecharts 并不会出现渲染上的错误，但不符合 Echarts 中对 title 的要求.
+
+
+第二，为了提高性能，pyecharts 作了以下几点处理：
+
+- 函数翻译的实际执行是在 `render` 函数调用时，而不是 `add` 函数。
+- 对已经翻译完成的函数以 **函数名** 为索引进行缓存，避免多次渲染同名函数。
+
+因此应当避免同一个函数名多用，以下的情况可能无法获得预期的效果。
+
+```python
+from pyecharts import Bar
+
+def label_formatter(params):
+    return params.name + ' [Good!]'
+
+attr = ["Jan", "Feb"]
+v1 = [2.0, 4.9]
+bar = Bar("Bar chart", "precipitation and evaporation one year")
+bar.add("precipitation", attr, v1, is_label_show=True, label_formatter=label_formatter)
+bar.render()
+
+def label_formatter(params):
+    return params.name + '[OK!]'
+
+bar2 = Bar("Bar chart", "precipitation and evaporation one year")
+bar2.add("precipitation", attr, v1, is_label_show=True, label_formatter=label_formatter)
+bar2.render()
+```
diff --git a/docs/zh-cn/api.md b/docs/zh-cn/api.md
@@ -102,13 +102,13 @@ js 文件仓库路径。可以设置本地或者远程地址。所有的远程
 
 **on(event_name, handler)**
 
-添加[事件处理函数](http://echarts.baidu.com/api.html#events)。
+添加 [事件处理函数](http://echarts.baidu.com/api.html#events)。
 
 请注意，事件处理函数是在浏览器里运行，但是要求你用 Python 写哦。
 
 这是支持的所有事件
 
-```
+``` python
 # Mouse Events
 
 MOUSE_CLICK = 'click'
@@ -148,10 +148,9 @@ BRUSH_SELECTED = 'brushselected'
 
 事件处理函数的原型:
 
-```
+``` python
 def handler(params):
     ...
-
 ```
 
 此处 params 的结构与 echarts 的一模一样：
@@ -186,7 +185,7 @@ def handler(params):
 
 例子：
 
-```
+``` python
 # coding=utf-8
 from __future__ import unicode_literals
 
@@ -206,7 +205,7 @@ map.on(events.MOUSE_CLICK, on_click)
 map.render()
 ```
 
-![2018-04-21 23_31_34](https://user-images.githubusercontent.com/4280312/39089412-88f0436e-45be-11e8-91b1-6617d795f26e.gif)
+![](https://user-images.githubusercontent.com/4280312/39089412-88f0436e-45be-11e8-91b1-6617d795f26e.gif)
 
 **get_js_dependencies()**