Docs update (pyecharts#508)

* 格式化 setup.py * Fix: pyecharts#504 修复 markpoint 标记点标注不显示的 bug * Update: changelog 文档更新 * Update: docs update for v0.5.0 * Update release note * Update datasets docs * Update: micro docs update * 🐛 fix a typo
Edward125 · Apr 28, 2018 · 02db99a · 02db99a
1 parent ad2b2be
commit 02db99a
Show file tree

Hide file tree

Showing 12 changed files with 95 additions and 98 deletions.
diff --git a/.gitignore b/.gitignore
@@ -94,4 +94,4 @@ ENV/
 .DS_store
 
 # for vscode
-.vscode/
+.vscode/
diff --git a/docs/README.md b/docs/README.md
@@ -27,5 +27,5 @@ pyecharts 是一个用于生成 Echarts 图表的类库。Echarts 是百度开
 
 **项目开发**
 
-[技术文档](zh-cn/technical_docs) |  [开发团队](zh-cn/team) | [赞助者名单](zh-cn/donors)  | [FAQ](zh-cn/faq)
+[技术文档](zh-cn/technical) |  [开发团队](zh-cn/team) | [赞助者名单](zh-cn/donors)  | [FAQ](zh-cn/faq)
 
diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md
@@ -27,5 +27,5 @@ pyecharts 是一个用于生成 Echarts 图表的类库。Echarts 是百度开
 
 **项目开发**
 
-[技术文档](zh-cn/technical_docs) |  [开发团队](zh-cn/team) | [赞助者名单](zh-cn/donors)  | [FAQ](zh-cn/faq)
+[技术文档](zh-cn/technical) |  [开发团队](zh-cn/team) | [赞助者名单](zh-cn/donors)  | [FAQ](zh-cn/faq)
 
diff --git a/docs/zh-cn/advanced.md b/docs/zh-cn/advanced.md
@@ -17,14 +17,14 @@ pyecharts 目前仅使用了并封装一部分的 Javascripthon 的翻译规则
 
 比如能够将以下的 Python 函数：
 
-```
+```python
 def add(x, y):
     return x + y
 ```
 
 翻译为以下 Javascript 函数。
 
-```
+```js
 function add(x, y) {
     return (x + y);
 }
@@ -38,7 +38,7 @@ function add(x, y) {
 
 pyecharts 默认已经安装了 pyecharts-javascripthon ，同时也可以通过 pip 安装。
 
-```
+```bash
 $ pip install pyecharts-javascripthon 
 ```
 
@@ -74,7 +74,6 @@ 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) 。
@@ -214,6 +213,7 @@ def test_mouse_click():
 第一，pyecharts 并不会检查 echarts 图表配置选项是否支持回调函数，关于这一部分可参考 ECharts 文档。
 
 这里指的是，options 参数本身是否支持回调函数，比如
+
 ```python
 def my_title():
     return 'my_title'

diff --git a/docs/zh-cn/changelog.md b/docs/zh-cn/changelog.md
@@ -4,7 +4,7 @@
 
     #### Added
     * [issue#311](https://github.com/pyecharts/pyecharts/issues/311) 提供 Jupyter Notebook 导出为 PDF 没有图片的解决方案
-    * 新增对 JavaScript 回调函数配置项和事件绑定的支持。详细内容请移步至 [release-note/v050](https://github.com/pyecharts/pyecharts/blob/master/docs/zh-cn/release-note/v050.md)。
+    * 新增对 JavaScript 回调函数配置项和事件绑定的支持。详细内容请移步至 [release-note/v050](zh-cn/release-note/v050)。
 
     #### Fixed
     * [issue#448](https://github.com/pyecharts/pyecharts/issues/448) 修复 Timeline 中 Overlap 图的 label_color 配置项不生效的 bug

diff --git a/docs/zh-cn/datasets.md b/docs/zh-cn/datasets.md
@@ -76,4 +76,26 @@ print(result)
 
 ## 地图数据
 
-地图数据均托管在 https://github.com/echarts-maps 。
+
+
+以下是 pyecharts 开发组托管的地图扩展（map extension）:
+
+1. [World countries include China map and World map](https://echarts-maps.github.io/echarts-countries-js/): [echarts-countries-pypkg](https://github.com/pyecharts/echarts-countries-pypkg) (1.9MB)
+2. [Chinese provinces and regions](https://echarts-maps.github.io/echarts-china-provinces-js/): [echarts-china-provinces-pypkg](https://github.com/pyecharts/echarts-china-provinces-pypkg) (730KB)
+3. [Chinese cities](https://echarts-maps.github.io/echarts-china-cities-js/): [echarts-china-cities-pypkg](https://github.com/pyecharts/echarts-china-cities-pypkg) (3.8MB)
+4. [Chinese counties](https://echarts-maps.github.io/echarts-china-counties-js/): [echarts-china-counties-pypkg](https://github.com/pyecharts/echarts-china-counties-pypkg) (4.1MB)
+5. [Custom Chinese regions](https://echarts-maps.github.io/echarts-china-misc-js/): [echarts-china-misc-pypkg](https://github.com/pyecharts/echarts-china-misc-pypkg) (148KB)
+6. [United Kingdom map](https://echarts-maps.github.io/echarts-united-kingdom-js/): [echarts-united-kingdom-pypkg](https://github.com/pyecharts/echarts-united-kingdom-pypkg) (1MB)
+
+更多的地图数据可查看 https://github.com/echarts-maps 。
+
+可以使用 *pip* 安装这些地图扩展。
+
+```
+$ pip install echarts-countries-pypkg
+$ pip install echarts-china-provinces-pypkg
+$ pip install echarts-china-cities-pypkg
+$ pip install echarts-china-counties-pypkg
+$ pip install echarts-china-misc-pypkg
+$ pip install echarts-united-kingdom-pypkg
+```
diff --git a/docs/zh-cn/faq.md b/docs/zh-cn/faq.md
@@ -36,18 +36,16 @@ jupyter notebook 输出后，你的 notebook 离开了本地 jupyter 环境，
 为了解决这个问题，再画图之前，你可以多加两个语句：
 
 ```python
-...
 from pyecharts import online
 
 online()
-...
 ```
 
 这样，所有的脚本会从 github 下载。如果你连不上 Github, 你可以先把 https://github.com/pyecharts/assets 克隆一下。然后在你自己的服务器上，把整个 js 文件夹挂上去。
 
 下面我简单示范一下  
 
-```
+```bash
 $ git clone https://github.com/pyecharts/assets
 $ cd js
 $ python -m http.server # for python 2, use python -m SimpleHTTPServer
@@ -57,17 +55,16 @@ Serving HTTP on 0.0.0.0 port 8000 ...
 然后，再把本地服务器加进前面的语句：
 
 ```python
-...
 from pyecharts import online
 
 online(host="http://localhost:8000)
-...
 ```
 
 **Q:Python2 编码问题**
 
 默认的编码类型为 UTF-8，在 Python3 中是没什么问题的，Python3 对中文的支持好很多。但是在 Python2 中，请应用下面的语句，保证没有编码问题:
-```
+
+```python
 #!/usr/bin/python
 #coding=utf-8
 from __future__ import unicode_literals
@@ -133,6 +130,7 @@ Mode                LastWriteTime         Length Name
 -a----         2018/3/9     23:12             71 requirements.txt
 ```
 复制本文件夹到需要离线安装的电脑上，终端切换到该路径下
+
 ``` shell
 $ pip install --no-index -f ./ -r r requirements.txt
 $ pip install ./pyecharts
@@ -142,5 +140,5 @@ python 2.7, 3.4 用户提示：
 
 离线用法呢，你们有两个选择：
 
-1）拥抱 python 3.5+, 你们就不需要再做别的了
-2）在自己的机器上运行 [pyecharts-javascripthon-api-service](https://github.com/pyecharts/pyecharts-javascripthon-api-service). 这个服务呢，也是需要 python 3.5+ 的，所以如果你是个人用户的，可以就此打住，直接用 pip3 装 pyecharts v0.5.0 好了。
+1）拥抱 python 3.5+, 你们就不需要再做别的了  
+2）在自己的机器上运行 [pyecharts-javascripthon-api-service](https://github.com/pyecharts/pyecharts-javascripthon-api-service). 这个服务呢，也是需要 python 3.5+ 的，所以如果你是个人用户的，可以就此打住，直接用 pip3 装 pyecharts v0.5.0 好了。
diff --git a/docs/zh-cn/release-note/_sidebar.md b/docs/zh-cn/release-note/_sidebar.md
@@ -1,2 +1,3 @@
+- [v0.5.0](zh-cn/release-note/v050)
 - [v0.3.2](zh-cn/release-note/v032)
-- [v0.3.0](zh-cn/release-note/v030)
+- [v0.3.0](zh-cn/release-note/v030)
diff --git a/docs/zh-cn/release-note/v050.md b/docs/zh-cn/release-note/v050.md
@@ -1,83 +1,51 @@
 # pyecharts V0.5.0 发布日志
 
-> pyecharts V0.5.0 发布，这是一个重大更新的版本。
+> pyecharts V0.5.0 发布，这是一个重大更新的版本。pyecharts 支持 *javascript 回调函数* 和 *echarts 事件处理函数* ，进一步覆盖 [ECharts](http://echarts.baidu.com/) 相关特性，为项目发展注入新的活力。
 
-## 1. 重构 option 配置项代码
 
-为了使代码结构更加合理，已将关于 echarts 配置项逻辑相关部分的代码文件移动至新的包 `echarts` 中，并重构了 `option.py` 文件的代码，将其中 `axis`，`label`，`line` 配置部分抽象成单独的类。
-
-
-## 2. 新增对 JavaScript 回调函数的支持
+## 1. 新增对 JavaScript 回调函数的支持
 
-v0.5.0 引入了新的 pyecharts 扩展包 [pyecharts-javascripthon](https://github.com/pyecharts/pyecharts-javascripthon)，该包的引入为 pyecharts 注入了新的活力。pyecharts-javascripthon 使用了一个优秀的第三方 Python 库 [metapensiero.pj](https://github.com/metapensiero/metapensiero.pj)，该库的官方介绍是 *Javascript for refined palates: a Python 3 to ES6 Javascript translator*，很明显了，这是一个用于将 Python 代码转换为 Javascript 代码的工具。
+pyecharts 已经封装了底层相关逻辑，对使用者是透明的。因此你可以像之前一样的使用。将回调函数对象通过 `add` 方法赋值到 echarts 配置字典中，这里的回调函数需满足以下条件之一：
 
-下面是几个简单的示例，
+- 使用 `def` 定义的命名函数
 
-python 代码
+注意的是目前暂不支持 `lambda` 表达式。
 
-``` python
-def foo(a, b, c):
-    pass
-```
-经转换，成为 JavaScript 代码
-``` js
-function foo(a, b, c) {
-}
-```
-
-python 代码
+例子：
 
 ```python
-def foo(a, b, c):
-    for i in range(a, b, c):
-        yield i
-
-for i in iterable(foo(0, 5, 2)):
-    print(i)
-```
-经转换，成为 JavaScript 代码
-``` js
-function* foo(a, b, c) {
-    for ... { // loop control omitted for brevity
-        yield i;
-    }
-}
-
-for (var i of foo(0, 5, 2)) {
-    console.log(i);
-}
-```
-
-关于该库的更多用法就不在这里展开了，请用户移步至 [官方文档](https://github.com/metapensiero/metapensiero.pj) 进行更详细的了解。
-
-有了这个库后，从本版本开始，pyecharts 将支持在配置项中传入 Python Function 类型的参数，对应的 Function 将会在 render 时自动的被转换成 Javascript 代码写入到 html 文件中，这也解决了 pyecharts 一直以来的一个痛点，缺乏对回调函数的支持，类似 formatter 这样的配置项一直无法得到较好的支持。
+from pyecharts import Bar
 
-**NOTE:** Python2.7-3.4 的用户使用时请确保系统可以联网。
 
-举个例子，pyecharts 用户经常会提问 Geo 图中如何在 tooltip 中只显示地图坐标名称和数值，不显示经纬度。
+def label_formatter(params):
+    return params.value + ' [Good!]'
 
-像这样
 
-![](https://user-images.githubusercontent.com/19553554/39248236-186a50ae-48ce-11e8-84eb-e58ba17eca5c.png)
+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()
+```
 
-而现在，你可以这么操作，先定义一个函数
+效果图
 
-```python
-def geo_formatter(params):
-    return params.name + ' : ' + params.value[2]
-```
+![bar-label-formatter-preview](https://user-images.githubusercontent.com/9875406/38666230-07c1aa66-3e71-11e8-9e9f-43fb7d707a64.png)
 
-然后设置 `tooltip_formatter=geo_formatter`，就能得到这样的效果
+pyecharts 使用 [pyecharts-javascripthon](https://github.com/pyecharts/pyecharts-javascripthon) 封装底层的逻辑，实现了一个 Python-To-Javascript 语言翻译器。该翻译器依据环境采用不同的实现方式。 Python2.7-3.4 的用户使用时请确保系统可以联网。
 
-![](https://user-images.githubusercontent.com/19553554/39248244-1be6da4a-48ce-11e8-931f-059879c5dcf4.png)
+| Python 版本 | 模式     |
+| ----------- | -------- |
+| 2.7 , 3.4   | 在线模式 |
+| 3.5+        | 本地模式 |
 
-本新功能需要用户对 metapensiero.pj 和 Echarts 官方配置项有一定的了解。更多详细内容请参考 [高级用法篇]()
+更多详细内容请参考 [Translator 篇](zh-cn/translator) 以及 [高级用法篇](zh-cn/advanced) 。
 
-## 3. 支持 JavaScript 原生事件
+## 2. 支持 JavaScript 原生事件
 
 Echarts 本身提供了 [api/events](http://echarts.baidu.com/api.html#events) 事件处理函数，主要通过 on 方式实现。
 
-pyecharts 根据官方提供的 events 列表，提供了如下全局事件名变量。位于 `pyecharts.echarts.events` 包中。
+pyecharts 根据官方提供的 events 列表，提供了如下全局事件名变量。位于 `pyecharts.echarts.events` 模块中。
 
 ``` python
 # Mouse Events
@@ -142,4 +110,13 @@ def test_mouse_click():
 
 ![](https://user-images.githubusercontent.com/19553554/39252189-b02b5420-48d7-11e8-9c53-6f0fb6d386c0.gif)
 
-关于点击事件更多详细内容请参考 [高级用法篇]()
+关于点击事件更多详细内容请参考 [高级用法篇](zh-cn/advanced) 。
+
+## 3. 重构 option 配置项代码
+
+为了使代码结构更加合理，已将关于 echarts 配置项逻辑相关部分的代码文件移动至新的包 `echarts` 中，并重构了 `option.py` 文件的代码，将其中 `axis`，`label`，`line` 配置部分抽象成单独的类。
+
+## 4 其他更新
+
+- [issue#448](https://github.com/pyecharts/pyecharts/issues/448) 修复 Timeline 中 Overlap 图的 label_color 配置项不生效的 bug
+- [issue#504](https://github.com/pyecharts/pyecharts/issues/504) 修复 markpoint 标记点标注不显示的 bug
diff --git a/docs/zh-cn/technical.md b/docs/zh-cn/technical.md
@@ -0,0 +1,14 @@
+> 技术文档篇：介绍 pyecharts 开发过程中所使用的工具、实践规范。
+
+## 开发工具
+
+- [Travis CI](https://travis-ci.org) ：在线构建工具
+- [AppVeyor CI](https://www.appveyor.com/) ：Windows 构建工具
+- [Codecov](https://codecov.io)：代码覆盖率
+- [nose](http://nose.readthedocs.io/en/latest/index.html) ：单元测试工具
+- [flake8](http://flake8.pycqa.org/en/latest/index.html) ：静态代码检查
+- [McCabe](https://pypi.org/project/mccabe/) ：复杂度检测工具
+
+## 文档构建工具
+
+主网站 [pyechart.org](http://pyecharts.org) 由 [docsify](https://docsify.js.org/) 构建。
diff --git a/docs/zh-cn/technical_docs.md b/docs/zh-cn/technical_docs.md
diff --git a/docs/zh-cn/translator.md b/docs/zh-cn/translator.md
@@ -60,9 +60,6 @@ myChart_09de949b428d4e5db7782a12a7541e35.on("click", on_click);
 ```
 
 
-
-
-
 ## 模拟对象(dummy objects)
 
 这些 API 定义了 Javascript 的一些函数和对象的适配。
@@ -88,21 +85,23 @@ from pyecharts_javascripthon.dom import Date as JDate
 from pyecharts_javascripthon import dom
 ```
 
-
-
 ### DOM 对象
 
 [Date](https://www.w3schools.com/jsref/jsref_obj_date.asp), [Math](https://www.w3schools.com/jsref/jsref_obj_math.asp), [JSON](https://www.w3schools.com/jsref/jsref_obj_json.asp), [window](https://www.w3schools.com/jsref/obj_window.asp), [Document](https://www.w3schools.com/jsref/dom_obj_document.asp), [console](https://www.w3schools.com/jsref/obj_console.asp), [screen](https://www.w3schools.com/jsref/obj_screen.asp)
 
-```
+``` python
 from pyecharts_javascripthon.dom import window    # for window object
 from pyecharts_javascripthon.dom import Document  # for Document object
 from pyecharts_javascripthon.dom import Date      # for Date object
+from pyecharts_javascripthon.dom import Math      # for Math module
+from pyecharts_javascripthon.dom import JSON      # for JSON module
+from pyecharts_javascripthon.dom import screen    # for screen object
+from pyecharts_javascripthon.dom import console   # for console object
 ```
 
 ### 全局函数
 
-```
+```python
 from pyecharts_javascripthon.dom import alert    # provide alert dialog to the user
 ```
 
@@ -112,4 +111,4 @@ from pyecharts_javascripthon.dom import alert    # provide alert dialog to the u
 
 pyecharts 开发组为项目提供了一个在线转换的代码的功能，实际上就是把代码 post 到一台支持 metapensiero.pj 运行环境的服务器，再将转换后的代码返回。[pyecharts-javascripthon-api-service](https://github.com/pyecharts/pyecharts-javascripthon-api-service) 承担了这部分的工作，现已将该项目部署到了 [Heroku](https://www.heroku.com/)。
 
-用户多了的话呢，免费资源会耗尽。如果想部署到自己服务器的开发者可以参考项目给出的 [文档](https://github.com/pyecharts/pyecharts-javascripthon-api-service/blob/master/README.md) 来操作。
+用户多了的话呢，免费资源会耗尽。如果想部署到自己服务器的开发者可以参考项目给出的 [文档](https://github.com/pyecharts/pyecharts-javascripthon-api-service/blob/master/README.md) 来操作。
Original file line number	Diff line number	Diff line change
Expand Up		@@ -27,5 +27,5 @@ pyecharts 是一个用于生成 Echarts 图表的类库。Echarts 是百度开

		项目开发

		[技术文档](zh-cn/technical_docs) \| [开发团队](zh-cn/team) \| [赞助者名单](zh-cn/donors) \| [FAQ](zh-cn/faq)
		[技术文档](zh-cn/technical) \| [开发团队](zh-cn/team) \| [赞助者名单](zh-cn/donors) \| [FAQ](zh-cn/faq)