dark, vintage, macarons, infographic, shine and roma themes (pyechart…

…s#530)

* 🐛 turn on split line for scatter diagram. fix pyecharts#516

* 🔥 remove documentation that echos the function name

* ✨ support dark theme. fix pyecharts#512

* ✨ support global_theme in configure function. improves pyecharts#512

* ✨ use_theme, related to pyecharts#512

* ✨ support 5 more external themes which come from echarts-themes-pypkg and echarts-themes-js, pyecharts#512

* 📰 add missing test fixtures

* 💚 make unit test pass

* 📚 document themes usage

* 📚 add cross reference

* 📚 update change log and pump version

* Update: update some docs

* Update: typo fixed

* Update: prepare docs update

* Update: 鉴于现在 md 做 long description 效果不佳，转化为 rst 又出现问题，所以暂时取消

* Fix: fixed broken test, remove unused codecs

docs/zh-cn/_sidebar.md

@@ -5,6 +5,7 @@ pyecharts 是一个用于生成 Echarts 图表的类库。Echarts 是百度开
   - [图表配置](zh-cn/charts)
 - 高级话题
   - [图表 API](zh-cn/api)
+  - [自定义主题](zh-cn/themes)
   - [自定义地图](zh-cn/customize_map)
   - [回调函数和事件处理](zh-cn/advanced)
   - [语言翻译扩展](zh-cn/translator)

docs/zh-cn/api.md

@@ -24,25 +24,33 @@ pyecharts 遵循 “先配置后使用” 的基本原则，所有的配置项
 
 ```python
 import pyecharts
-pyecharts.configure(P1=V1, P2=V2,...)
+pyecharts.configure(
+    jshost=None,
+    echarts_template_dir=None,
+    force_js_embed=None,
+    output_image=None,
+    global_theme=None
+)
 ```
 
-### 配置列表
-
-**echarts_template_dir**
-
-模板文件目录，默认值：'.'（当前目录）。用于自定义模板文件，即 `render` 的 template_name 参数构成全部的路径。
-
-**jshost**
-
+* jshost
 js 文件仓库路径。可以设置本地或者远程地址。所有的远程地址必须以 `http://` 或者 `https://` 开头。  
 也可以使用 `pyecharts.online()` 函数设置此选项。  
 为了保持兼容性， jshost 并不是必须使用 '/' 等分隔符作为结尾。
 
-**force_js_embed**
+* echarts_template_dir
+模板文件目录，默认值：'.'（当前目录）。用于自定义模板文件，即 `render` 的 template_name 参数构成全部的路径。
 
+* force_js_embed
 是否强制采用内部嵌入方式渲染js文件标签， `echarts_js_dependencies`  模板函数受此影响，具体可参考该函数。
 
+* output_image
+指定输出图片类型，有 'svg', 'jpeg', 'png' 可选
+
+* global_theme
+指定全局主题，目前提供的主题有 `vintage`, `macarons`, `infographic`, `shine` 和 `roma`。
+
+
 ## 图表类
 
 图表类是 pyecharts 库中最为核心的内容，每一个类代表了 [Echarts](http://echarts.baidu.com/) 中一个图表类型。下表显示了这些图表的继承体系。
@@ -103,6 +111,10 @@ js 文件仓库路径。可以设置本地或者远程地址。所有的远程
 
 添加 [事件处理函数](http://echarts.baidu.com/api.html#events)。
 
+* event_name：事件名称
+* handler：回调函数
+
+
 这是支持的所有事件
 
 ``` python
@@ -147,7 +159,7 @@ BRUSH_SELECTED = 'brushselected'
 
 ``` python
 def handler(params):
-    ...
+    pass
 ```
 
 此处 params 的结构与 echarts 的一模一样：
@@ -307,6 +319,15 @@ EChartsEnvironment 类继承自 `BaseEnvironment` 。并在此基础上改写了
 
 包含模板函数的字典。可用于 web 框架整合。
 
+### 引擎方法
+
+**create_default_environment(filet_ype)**
+
+* file_type: 输出文件类型，有 'html', 'svg', 'png', 'jpeg', 'gif'，'pdf' 可选
+
+为渲染创建一个默认配置环境
+
+
 ### 模板函数
 
 pyecharts 内置的引擎提供了一些模板函数，这些函数通常接收一个或多个的 `Chart` 或 `Page` 的参数，详细的调用形式见下表。

docs/zh-cn/changelog.md

@@ -1,9 +1,14 @@
 # 版本日志
 
-* ### version 0.5.2（dev）
-    * TODO
+* ### version 0.5.3（dev）
+    *  TODO
 
-* ### version 0.5.1 - 2018.05.02（Current）
+* ### version 0.5.2 - 2018.05.04（Current）
+
+    #### Added
+    * [issue#512](https://github.com/pyecharts/pyecharts/issues/512) 新增自定义主题功能
+
+* ### version 0.5.1 - 2018.05.02
 
     #### Fixed
     * [issue#516](https://github.com/pyecharts/pyecharts/issues/516) 修复直角坐标系图 X 轴分隔符展示效果不一致的 bug

docs/zh-cn/jupyter_notebook.md

@@ -1,8 +1,6 @@
-# pyecharts 文档 - Jupyter Notebook
+# Jupyter Notebook
 
-## 概述
-
-pyecharts 支持在 Jupyter Notebook 环境中显示渲染图表以及导出其他形式的文件。
+> pyecharts 支持在 Jupyter Notebook 环境中显示渲染图表以及导出其他形式的文件。
 
 ## 安装
 
@@ -31,58 +29,71 @@ Known nbextensions:
 
 ## 显示图表
 
-在 Cell 中，可以直接调用实例本身实例来显示图表，目前所有的类已经实现了  [IPython Rich Display](http://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display) 的 `_repr_html_` 方法。
+在 Cell 中，可以直接调用实例本身来显示图表，目前所有的类已经实现了 [IPython Rich Display](http://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display) 的 `_repr_html_` 方法。
 
 ![pandas-numpy](https://user-images.githubusercontent.com/19553554/35104252-3e36cee2-fca3-11e7-8e43-09bbe8dbbd1e.png)
 
 ## 导出 html 功能
 
 可以使用 Notebook 默认的 "download as" 导出其他形式的文件，比如 ipynb 或者图片。
 
-**重要** ：由于导出后的文件脱离了原有 Jupyter Notebook 环境，为了能够完整的显示图表，应当使用远程 jshost 库。
+**NOTE:** 由于导出后的文件脱离了原有 Jupyter Notebook 环境，为了能够完整的显示图表，应当使用远程 jshost 库。
 
 ```python
 from pyecharts import online
 
-online()
+online() # 使用远程 jshost
 ```
 
-
 如果导出的 HTML 文件需要在没有网路的情况下显示图片，请考虑后面的介绍。
 
 ## 导出 PDF 功能
 
-一直以来 PDF 输出的问题困恼着 pyecharts 用户。目前的解决方案是结合 pyecharts-snapshot 来生成静态图片，然后输出。用户需要做两件事情：
+用户可以结合 pyecharts-snapshot 来生成静态图片，然后输出。需要执行一下两个步骤。
 
-第一就是装 [pyecharts-snapshot 0.1.4+ 和 phanomjs-prebuilt](https://github.com/pyecharts/pyecharts-snapshot#installation)
-
-第二就是在 notebook 的最开始添上一下语句。这样就可以输出图片成 PDF 了。
+1. 安装 [pyecharts-snapshot 0.1.4+ 和 phanomjs-prebuilt](https://github.com/pyecharts/pyecharts-snapshot#installation)
+2. 在 notebook 的最开始添上一下语句。这样就可以输出图片成 PDF 了。
 
 ```python
-from pyecharts import configure
+from pyecharts import Bar, configure
 
-configure(output_image='png')
+configure(output_image='pdf')
+
+bar = Bar("我的第一个图表", "这里是副标题")
+bar.add("服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90])
+bar # 将在 jupyter 中显示为 pdf 文件，并不保存为本地 pdf 文件。
 ```
 
 请看这个例子: [test.pdf](https://github.com/pyecharts/pyecharts/files/1813293/test.6.pdf)
 
-## 导出的 HTML 文件， 在没有互联网，怎么样打开图片
+## 离线显示 HTML 中的图片
 
-这个时候， 你也需要装 pyecharts-snapshot 0.1.4+ 。你需要用 `renderer` 参数让 pyecharts 0.4.2+ 生成 svg 图片并且加上下面的语句。
+用户需要装 pyecharts-snapshot 0.1.4+，并使用 `renderer` 参数让 pyecharts 0.4.2+ 生成 svg 图片。
 
 ```python
 from pyecharts import configure
 
 configure(output_image='svg')
 ```
 
-同时，请注意，这个配置也是可以输出 PDF 的。可就是输出的图片不仅需要 Inkscape，输出图片效果很不好。所以不推荐用 `output_image='svg'`。
+**NOTE:** `svg` 下也是可以输出 PDF 的。可就是输出的图片不仅需要 Inkscape 且图片效果很不好。所以不推荐用 `output_image='svg'` 输出为 PDF。
 
 ## 示例
 
 参见 [pyecharts示例](https://github.com/pyecharts/pyecharts-users-cases) 。
 
+## 主题
+
+自 pyecharts 0.5.2+ 之后，用户通过图表的 `use_theme` 函数配置单个图形的主题。如果想配置运行环境内所有图表的主题，可以在 notebook 的最开始添上以下语句：
+
+```python
+from pyecharts import configure
+
+configure(global_theme='dark')
+```
+
+然后在重新运行，奇迹就会发生。
+
 ## jupyterlab
 
 [jupyterlab](https://github.com/jupyterlab/jupyterlab) 是下一代 Jupyter Notebook ，目前尚处于发展的雏形之中。我们将进一步关注项目发展，尽可能第一时间实现 pyecharts 的适配，敬请期待。
-

docs/zh-cn/prepare.md

@@ -8,60 +8,77 @@ from pyecharts import Bar
 
 bar = Bar("我的第一个图表", "这里是副标题")
 bar.add("服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90])
-bar.print_echarts_options()
-bar.render()
+# bar.print_echarts_options() # 该行只为了打印配置项，方便调试时使用
+bar.render()    # 生成本地 HTML 文件
 ```
 ![guide-0](https://user-images.githubusercontent.com/19553554/35103909-3ee41ba2-fca2-11e7-87be-1a3585b9e0fa.png)
 
 
 * ```add()```  
-    主要方法，用于添加图表的数据和设置各种配置项  
+    主要方法，用于添加图表的数据和设置各种配置项
 * ```print_echarts_options()```  
     打印输出图表的所有配置项
 * ```render()```  
-    默认将会在根目录下生成一个 render.html 的文件，支持 path 参数，设置文件保存位置，如 render(r"e:\my_first_chart.html")，文件用浏览器打开。  
+    默认将会在根目录下生成一个 render.html 的文件，支持 path 参数，设置文件保存位置，如 render(r"e:\my_first_chart.html")，文件用浏览器打开。
 
-**Note：** 可以按右边的下载按钮将图片下载到本地，如果想要提供更多实用工具按钮，请在 `add()` 中设置 `is_more_utils` 为 True  
+**Note：** 可以按右边的下载按钮将图片下载到本地，如果想要提供更多实用工具按钮，请在 `add()` 中设置 `is_more_utils` 为 True
 
 ```python
 from pyecharts import Bar
 
 bar = Bar("我的第一个图表", "这里是副标题")
-bar.add("服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90],
+bar.add("服装", 
+        ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90],
         is_more_utils=True)
 bar.render()
 ```
 ![guide-1](https://user-images.githubusercontent.com/19553554/35104150-f31e1b7c-fca2-11e7-81cf-a12bf1629e02.png)
 
+### 使用主题
+
+自 0.5.2+ 起，pyecharts 支持更换主体色系。下面是跟换为 'dark' 的例子：
+
+```python
+from pyecharts import Bar
+
+bar = Bar("我的第一个图表", "这里是副标题")
+bar.use_theme('dark')
+bar.add("服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90])
+bar.render()
+```
+![guide-2](https://user-images.githubusercontent.com/4280312/39617664-79789878-4f78-11e8-9f0e-c3a2c371b6cb.png)
+
+pyecharts 支持另外 5 个主体色系，[请移步到主题色系获取更多配置信息](zh-cn/themes)。
+
+
 ### 使用 pyecharts-snapshot 插件
-如果想直接将图片保存为 png, pdf, gif 格式的文件，可以使用 [pyecharts-snapshot](https://github.com/pyecharts/pyecharts-snapshot)。使用该插件请确保你的系统上已经安装了 node.js 环境，如果没有，请到这里下载 [https://nodejs.org/en/download/](https://nodejs.org/en/download/)
 
-1. 安装 phantomjs  
-    `npm install -g phantomjs-prebuilt`
-2. 安装 pyecharts-snapshot  
-    `pip install pyecharts-snapshot`
-3. 引入 pyecharts-snapshot  
-    `from pyecharts_snapshot.main import make_a_snapshot`
-4. 调用方法  
-    `make_a_snapshot('render.html', 'snapshot.png')`  
-    make_a_snapshot() 第一个参数为生成的 .html 文件，第二个参数为要保存的文件，可以为 png/pdf/gif
+如果想直接将图片保存为 png, pdf, gif 格式的文件，可以使用 [pyecharts-snapshot](https://github.com/pyecharts/pyecharts-snapshot)。使用该插件请确保你的系统上已经安装了 [Nodejs](https://nodejs.org/en/download/) 环境。
 
-更多内容请移步至 [pyecharts-snapshot](https://github.com/pyecharts/pyecharts-snapshot)  
+1. 安装 phantomjs
+    `$ npm install -g phantomjs-prebuilt`
+2. 安装 pyecharts-snapshot
+    `$ pip install pyecharts-snapshot`
+3. 调用 `render` 方法
+    `bar.render(path='snapshot.png')`
+    文件结尾可以为 svg/jpeg/png/pdf/gif。请注意，svg 文件需要你在初始化 bar 的时候设置 renderer='svg'。
+
+更多内容请移步至 [pyecharts-snapshot](https://github.com/pyecharts/pyecharts-snapshot)
 
 
 ### 图形绘制过程
+
 基本上所有的图表类型都是这样绘制的：
 1. ```chart_name = Type()``` 初始化具体类型图表。
 2. ```add()``` 添加数据及配置项。
-3. ```render()``` 生成 .html 文件。  
+3. ```render()``` 生成本地文件（html/svg/jpeg/png/pdf/gif）。
 
-```add()``` 数据一般为两个列表（长度一致）。  
-如果你的数据是字典或者是带元组的字典。可利用 ```cast()``` 方法转换。
+```add()``` 数据一般为两个列表（长度一致）。如果你的数据是字典或者是带元组的字典。可利用 ```cast()``` 方法转换。
 
 ```python
 @staticmethod
 cast(seq)
-转换数据序列，将带字典和元组类型的序列转换为 k_lst,v_lst 两个列表 
+转换数据序列，将带字典和元组类型的序列转换为 k_lst,v_lst 两个列表
 ```
 1. 元组列表  
     [(A1, B1), (A2, B2), (A3, B3), (A4, B4)] --> k_lst[ A[i1, i2...] ], v_lst[ B[i1, i2...] ]
@@ -72,23 +89,7 @@ cast(seq)
 
 ### 多次显示图表
 
-> v0.4.0 更新
-
-在 pyecharts 可以连续使用 `chart.render` 在同一个脚本中显示多个图表。
-
-```python
-from pyecharts import Bar, Line
-
-bar = Bar("我的第一个图表", "这里是副标题")
-bar.add("服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90])
-bar.render(path='bar.html')
-
-line = Line("我的第一个图表", "这里是副标题")
-line.add("服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90])
-line.render(path='line.html')
-```
-
-从 v0.4.0 开始，pyecharts 重构了渲染的内部逻辑，改善效率。推荐使用以下方式显示多个图表。
+从 v0.4.0+ 开始，pyecharts 重构了渲染的内部逻辑，改善效率。推荐使用以下方式显示多个图表。
 
 ```python
 from pyecharts import Bar, Line
@@ -100,26 +101,30 @@ bar.add("服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "
 line = Line("我的第一个图表", "这里是副标题")
 line.add("服装", ["衬衫", "羊毛衫", "雪纺衫", "裤子", "高跟鞋", "袜子"], [5, 20, 36, 10, 75, 90])
 
-env = create_default_environment()
+env = create_default_environment("html")
+# 为渲染创建一个默认配置环境
+# create_default_environment(filet_ype)
+# file_type: 'html', 'svg', 'png', 'jpeg', 'gif' or 'pdf'
 
 env.render_chart_to_file(bar, path='bar.html')
 env.render_chart_to_file(line, path='line.html')
 ```
 
 相比第一个例子，该代码只是使用同一个引擎对象，减少了部分重复操作，速度有所提高。
 
-
 ### Pandas&Numpy 简单示例
+
 如果使用的是 Numpy 或者 Pandas，可以参考这个示例
 
 ![pandas-numpy](https://user-images.githubusercontent.com/19553554/35104252-3e36cee2-fca3-11e7-8e43-09bbe8dbbd1e.png)
 
 **Note：** 使用 Pandas&Numpy 时，整数类型请确保为 int，而不是 numpy.int32
 
-**当然你也可以采用更加酷炫的方式，使用 Jupyter Notebook 来展示图表，matplotlib 有的，pyecharts 也会有的**  
-**Note：** 从 v0.1.9.2 版本开始，废弃 ```render_notebook()``` 方法，现已采用更加 pythonic 的做法。直接调用本身实例就可以了。  
+**当然你也可以采用更加酷炫的方式，使用 Jupyter Notebook 来展示图表，matplotlib 有的，pyecharts 也会有的**
+
+**Note：** 从 v0.1.9.2 版本开始，废弃 ```render_notebook()``` 方法，现已采用更加 pythonic 的做法。直接调用本身实例就可以了。
 
-比如这样  
+比如这样
 
 ![notebook-0](https://user-images.githubusercontent.com/19553554/35104153-f6256212-fca2-11e7-854c-bacc61eabf6f.gif)
 
@@ -133,17 +138,4 @@ env.render_chart_to_file(line, path='line.html')
 
 更多 Jupyter notebook 的例子请参考 [notebook-use-cases](https://github.com/pyecharts/pyecharts-users-cases)。可下载后运行看看。
 
-如需使用 Jupyter Notebook 来展示图表，只需要调用自身实例即可，同时兼容 Python2 和 Python3 的 Jupyter Notebook 环境。所有图表均可正常显示，与浏览器一致的交互体验，这下展示报告连 PPT 都省了！！  
-
-
-### 如果在没有互联网的情况下安装 pyecharts 0.3.2 +
-
-首先，您需要通过有互联网的计算机得到这三个包：pyecharts, pyecharts-jupyter-installer, 和 jupyter-echarts-pypkg. 
-
-然后，按照这个顺序组装：
-
-```
-pip install pyecharts-jupyter-installer.tar.gz
-pip install jupyter-echarts-pypkg.tar.gz
-pip install pyecharts.tar.gz
-```
+如需使用 Jupyter Notebook 来展示图表，只需要调用自身实例即可，同时兼容 Python2 和 Python3 的 Jupyter Notebook 环境。所有图表均可正常显示，与浏览器一致的交互体验，这下展示报告连 PPT 都省了！！