diff --git a/.gitignore b/.gitignore index f7be6f16..8f1560c1 100644 --- a/.gitignore +++ b/.gitignore @@ -8,7 +8,7 @@ __pycache__/ .idea # Distribution / packaging .Python -test/render.html +test/*.html env/ build/ develop-eggs/ diff --git a/CNAME b/CNAME new file mode 100644 index 00000000..cd67d942 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +pyecharts.org diff --git a/README.md b/README.md index e0276614..819542a4 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,28 @@ -# [pyecharts](https://github.com/pyecharts/pyecharts) [![Build Status](https://travis-ci.org/pyecharts/pyecharts.svg?branch=master)](https://travis-ci.org/pyecharts/pyecharts) [![codecov](https://codecov.io/gh/pyecharts/pyecharts/branch/master/graph/badge.svg)](https://codecov.io/gh/pyecharts/pyecharts) [![PyPI version](https://badge.fury.io/py/pyecharts.svg)](https://badge.fury.io/py/pyecharts) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +# [pyecharts](https://github.com/pyecharts/pyecharts) [![Build Status](https://travis-ci.org/pyecharts/pyecharts.svg?branch=master)](https://travis-ci.org/pyecharts/pyecharts) [![codecov](https://codecov.io/gh/pyecharts/pyecharts/branch/master/graph/badge.svg)](https://codecov.io/gh/pyecharts/pyecharts) [![PyPI version](https://badge.fury.io/py/pyecharts.svg)](https://badge.fury.io/py/pyecharts) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) -> pyecharts is a library to generate charts using Echarts. It simply provides the interface between Echarts and Python. +> pyecharts is a library to generate charts using Echarts. It simply provides the interface of 28+ kinds of charts between Echarts and Python. ## Introduction [Echarts](https://github.com/ecomfe/echarts) is an open source library from Baidu for data visualization in javascript. It has awesome demo pages so I started to look out for an interface library so that I could use it in Python. I ended up with [echarts-python](https://github.com/yufeiminds/echarts-python) on github but it lacks of documentation and was not updated for a while. Just like many other Python projects, I started my own project, pyecharts, referencing echarts-python and another library [pygal](https://github.com/Kozea/pygal). ## Installation -pyecharts works on Python2 and Python3. For more information please refer to [changelog.md](https://github.com/pyecharts/pyecharts/blob/master/changelog.md) +### Python Compatibility -### Jupyter-Notebook -Make sure you hava installed jupyter-notebook enviroment if you want to show your charts on notebook. -How to install it? -``` -$ pip install notebook +pyecharts works on Python2.7 and Python3.4+. + +pyecharts handles all strings and files with unicode encoding and you **MUST** use unicode string on Python 2. + +```python +#coding=utf-8 +from __future__ import unicode_literals ``` + ### pyecharts + You can install it via pip ``` -$ pip install pyecharts -U +$ pip install pyecharts ``` or clone it and install it @@ -30,6 +34,9 @@ $ python setup.py install ``` ## Basic Usage + +### Render to Local Html File + ```python from pyecharts import Bar @@ -42,50 +49,86 @@ bar.add("evaporation", attr, v2, mark_line=["average"], mark_point=["max", "min" bar.render() ``` -It will create a file named render.html in the root directory, open file with your borwser. +It will create a file named *render.html* in the root directory, open file with your borwser. -![usage-0](https://user-images.githubusercontent.com/19553554/35104516-036181b2-fca4-11e7-8008-4ff4044245ee.gif) +![usage-0](https://user-images.githubusercontent.com/19553554/35388262-078a4afc-020e-11e8-8acc-cc7bc8a4e8a6.gif) +### Export as Images or Pdf -## Working with pandas & numpy -![pandas-numpy](https://user-images.githubusercontent.com/19553554/35104252-3e36cee2-fca3-11e7-8e43-09bbe8dbbd1e.png) +[pyecharts-snapshot](https://github.com/pyecharts/pyecharts-snapshot) is a library which renders the output of pyecharts as a png, jpeg, gif image or a pdf file at command line or in your code. +See more detail at the repositoty. -## Working with Flask & Django -Flask +## Platform Support + +pyecharts exposes chart API and template API so that it can work on some common platforms. + +### Work on Jupyter Notebook + +In the Notebook cell ,you can simply call the instance itself to diplay the chart. + +All chart classes in pyecharts implement the `_repr_html_` interface about [IPython Rich Display](http://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display) . + +In the case of online jshost mode,you can also download as some file formats (ipynb/py/html/pdf) and run without jupyter notebook enviromnment. + +![pandas_numpy](https://user-images.githubusercontent.com/19553554/35104252-3e36cee2-fca3-11e7-8e43-09bbe8dbbd1e.png) + +### 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. + +Demo ![flask-0](https://user-images.githubusercontent.com/19553554/35081158-3faa7c34-fc4d-11e7-80c9-2de79371374f.gif) -Django +## Advance Topics -![django-0](https://user-images.githubusercontent.com/19553554/35081440-21efcf58-fc4f-11e7-8427-ed73306533e8.gif) +### Cusom Template FIles and Layout -* 中文文档 - * [pyecharts + Flask](https://github.com/pyecharts/pyecharts/blob/master/docs/zh-cn/doc_flask.md) - * [pyecharts + Django](https://github.com/pyecharts/pyecharts/blob/master/docs/zh-cn/doc_django.md) -* English - * [pyecharts + Flask](https://github.com/pyecharts/pyecharts/blob/master/docs/en-us/doc_flask.md) - * [pyecharts + Django](https://github.com/pyecharts/pyecharts/blob/master/docs/en-us/doc_django.md) +pyecharts exposes engine API so that you can use your own template file and integrate with CSS framework. +In addition,pyecharts also ships a lot of jinja2 template functions used in template files. + +### Custom Map Library + +All map is hosted by the repository [echarts-china-cities-js](https://github.com/pyecharts/echarts-china-cities-js) and [echarts-countries-js](https://github.com/pyecharts/echarts-countries-js) . ## Documentation -* [中文文档](https://github.com/pyecharts/pyecharts/tree/master/docs/zh-cn) -* [English](https://github.com/pyecharts/pyecharts/tree/master/docs/en-us) +* [中文文档](http://pyecharts.org/#/zh-cn/) +* [English Documentation](http://pyecharts.org/#/en-us/) + +## Examples + +All examples is hosted on the repository [pyecharts-users-cases](https://github.com/pyecharts/pyecharts-users-cases) . ## Test -If you work on Python2.7, please install `mock` library manually. +### Unit Test -Run as the following commands. +You should install the libraries in the requirements.txt files. -```shell -$ cd test -$ nosetests --with-coverage --cover-package pyecharts --cover-package test +``` +pip install -r test\requirements.txt ``` +And run with the [nose](https://nose.readthedocs.io/en/latest/) commands. + +```shell +$ make +``` + +### Quality Assurance + + [flake8](http://flake8.pycqa.org/en/latest/index.html) and [pylint](https://www.pylint.org/) are used to improve the quality of code. + +### Continuous Integration + +The project is developed with [Travis CI](https://travis-ci.org/) . + ## Author -pyecharts is developed and maintained by chenjiandongx ([chenjiandongx@qq.com](chenjiandongx@qq.com)) + +[![chenjiandongx](https://user-images.githubusercontent.com/19553554/35315207-02ea37ea-0106-11e8-9f9f-8fb26922c492.png)](https://github.com/chenjiandongx) [![chfw](https://user-images.githubusercontent.com/19553554/35315208-032a38a4-0106-11e8-85f1-7f601330027f.png)](https://github.com/chfw) [![kinegratii](https://user-images.githubusercontent.com/19553554/35315209-0368f8fa-0106-11e8-99f6-c71d7624a2c9.png)](https://github.com/kinegratii) ## License pyecharts is released under the MIT License. See LICENSE for more information. diff --git a/docs/README.md b/docs/README.md index f87f5c14..f1e81fb5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1 +1,26 @@ -# TODO \ No newline at end of file +# pyecharts 文档 + +[![Build Status](https://travis-ci.org/pyecharts/pyecharts.svg?branch=master)](https://travis-ci.org/pyecharts/pyecharts) [![codecov](https://codecov.io/gh/pyecharts/pyecharts/branch/master/graph/badge.svg)](https://codecov.io/gh/pyecharts/pyecharts) [![PyPI version](https://badge.fury.io/py/pyecharts.svg)](https://badge.fury.io/py/pyecharts) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) + + +pyecharts 是一个用于生成 Echarts 图表的类库。Echarts 是百度开源的一个数据可视化 JS 库。用 Echarts 生成的图可视化效果非常棒，pyecharts 是为了与 Python 进行对接，方便在 Python 中直接使用数据生成图。 + +**基本使用** + +[渲染图表](zh-cn/prepare) | [图表配置](zh-cn/charts) + +**高级话题** + +[图表 API](zh-cn/api) | [自定义地图](zh-cn/customize_map) + +**平台支持** + +[Jupyter Notebook](zh-cn/jupyter_notebook) | [Flask](zh-cn/flask) | [Django](zh-cn/django) | [web 框架整合](zh-cn/web_integration) + +**其他资源** + +[示例项目](https://github.com/pyecharts/pyecharts-users-cases) | [地图扩展项目](https://github.com/pyecharts/echarts-china-cities-js) + +**项目开发** + +[版本日志](zh-cn/changelog) | [发布日志](zh-cn/release-note/) | [开发团队](zh-cn/team) | [赞助者名单](zh-cn/donors) | [FAQ](zh-cn/faq) diff --git a/docs/_coverpage.md b/docs/_coverpage.md index b8d21d85..cc162d08 100644 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -2,9 +2,11 @@ # pyecharts -> pyecharts is a Python Echarts Plotting Library. +> A Python Echarts Plotting Library. - It simply provides the interface between Echarts and Python. +* Chart: 28+ kinds of charts +* Map: 300+ Chinese cities / 200+ countries and regions +* Platforms: Pure Python / Jupyter Notebook / Web Framework [GitHub](https://github.com/pyecharts/pyecharts/) diff --git a/docs/en-us/README.md b/docs/en-us/README.md index 00f8be31..6e7c64fb 100644 --- a/docs/en-us/README.md +++ b/docs/en-us/README.md @@ -1,5 +1,26 @@ -# [pyecharts](https://github.com/chenjiandongx/pyecharts) - [![Build Status](https://travis-ci.org/pyecharts/pyecharts.svg?branch=master)](https://travis-ci.org/pyecharts/pyecharts) [![codecov](https://codecov.io/gh/pyecharts/pyecharts/branch/master/graph/badge.svg)](https://codecov.io/gh/pyecharts/pyecharts) [![PyPI version](https://badge.fury.io/py/pyecharts.svg)](https://badge.fury.io/py/pyecharts) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +# pyecharts Document + +[![Build Status](https://travis-ci.org/pyecharts/pyecharts.svg?branch=master)](https://travis-ci.org/pyecharts/pyecharts) [![codecov](https://codecov.io/gh/pyecharts/pyecharts/branch/master/graph/badge.svg)](https://codecov.io/gh/pyecharts/pyecharts) [![PyPI version](https://badge.fury.io/py/pyecharts.svg)](https://badge.fury.io/py/pyecharts) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) -[Echarts](https://github.com/ecomfe/echarts) is an open source library from Baidu for data visualization in javascript. It has awesome demo pages so I started to look out for an interface library so that I could use it in Python. I ended up with [echarts-python](https://github.com/yufeiminds/echarts-python) on github but it lacks of documentation and was not updated for a while. Just like many other Python projects, I started my own project, pyecharts, referencing echarts-python and another library [pygal](https://github.com/Kozea/pygal). \ No newline at end of file +[Echarts](https://github.com/ecomfe/echarts) is an open source library from Baidu for data visualization in javascript. It has awesome demo pages so I started to look out for an interface library so that I could use it in Python. I ended up with [echarts-python](https://github.com/yufeiminds/echarts-python) on github but it lacks of documentation and was not updated for a while. Just like many other Python projects, I started my own project, pyecharts, referencing echarts-python and another library [pygal](https://github.com/Kozea/pygal). + +**Basic Usage** + +[Chart Render](en-us/prepare) | [Chart Options](en-us/charts) + +**Advance Topics** + +[Chart API](en-us/api) | [Custom Map](en-us/customize_map) + +**Platform Support** + +[Jupyter Notebook](en-us/jupyter_notebook) | [Flask](en-us/flask) | [Django](en-us/django) | [Web Integration](en-us/web_integration) + +**Other Resources** + +[Demo Projects](https://github.com/pyecharts/pyecharts-users-cases) | [Map Extension](https://github.com/pyecharts/echarts-china-cities-js) + +**Development** + +[Changelog](en-us/changelog) | [Release Note](en-us/release-note) | [Team](en-us/team) | [FAQ](en-us/faq) diff --git a/docs/en-us/_sidebar.md b/docs/en-us/_sidebar.md index e0505e5f..2a459bee 100644 --- a/docs/en-us/_sidebar.md +++ b/docs/en-us/_sidebar.md @@ -1,5 +1,7 @@ -- [Charts](en-us/doc_charts) -- [pyecharts+Flask](en-us/doc_flask) -- [pyecharts+Django](en-us/doc_django) -- [Web integration](en-us/doc_web_integration) -- [API](en-us/doc_api) \ No newline at end of file +- [Charts](en-us/charts) +- [pyecharts+Flask](en-us/flask) +- [pyecharts+Django](en-us/django) +- [pyecharts+Flask](en-us/flask) +- [pyecharts+Django](en-us/django) +- [Web integration](en-us/web_integration) +- [API](en-us/api) diff --git a/docs/en-us/doc_api.md b/docs/en-us/api.md similarity index 95% rename from docs/en-us/doc_api.md rename to docs/en-us/api.md index 8f5cb89a..919dae10 100644 --- a/docs/en-us/doc_api.md +++ b/docs/en-us/api.md @@ -83,7 +83,11 @@ Data type:dict.The config options for a chart。Each chart has its own format an **js_dependencies** -Data type:set.The js filename collections for a chart's dependencies.Every element do not contain the filename extension(.js).E.g `{'echarts.min', 'fujian'}` . +*Changed in v0.4* + +Data type:list.The js filename collections for a chart's dependencies.Every element do not contain the filename extension(.js).E.g `{'echarts.min', 'fujian'}` . + +> In previous v0.4, the js_dependencies returns a unordered set. ### Methods @@ -245,8 +249,8 @@ Which mode is used is determined by the `PyEchartsConfig.jshost` and `PyEcharts | ---------------------------------------- | ------------ | ----------- | ------------------------- | --------------------- | | `/template/js/echarts` | local | IE | Generate one file locally | Default value | | `'https://chfw.github.io/jupyter-echarts/echarts'` | remote | IE | Generate on file | switch using `online` | -| 其他本地模式 (如 `/static/js`) | local | EI | Integrate with Web | | -| 其他远程模式（如 `hthttps://cdn.bootcss.com/echarts/3.7.2`） | remote | EI | Use remote JS | | +| Other Local Host (E.g. `/static/js`) | local | EL | Integrate with Web | | +| Other Remote Host(E.g. `hthttps://cdn.bootcss.com/echarts/3.7.2`) | remote | EL | Use remote JS | | Example diff --git a/docs/en-us/doc_charts.md b/docs/en-us/charts.md similarity index 100% rename from docs/en-us/doc_charts.md rename to docs/en-us/charts.md diff --git a/docs/en-us/doc_django.md b/docs/en-us/django.md similarity index 100% rename from docs/en-us/doc_django.md rename to docs/en-us/django.md diff --git a/docs/en-us/doc_flask.md b/docs/en-us/flask.md similarity index 100% rename from docs/en-us/doc_flask.md rename to docs/en-us/flask.md diff --git a/docs/en-us/doc_for_pyechart_developer.md b/docs/en-us/for_pyechart_developer.md similarity index 100% rename from docs/en-us/doc_for_pyechart_developer.md rename to docs/en-us/for_pyechart_developer.md diff --git a/docs/en-us/jupyter_notebook.md b/docs/en-us/jupyter_notebook.md new file mode 100644 index 00000000..e7accaf4 --- /dev/null +++ b/docs/en-us/jupyter_notebook.md @@ -0,0 +1,63 @@ +# pyecharts Document - Jupyter Notebook + +## Overview + +You can show charts and export to some file formats in the Jupyter Notebook. + +## Installation + +When install the *pyecharts* package using the following command, a jupyter nbextension named *echarts/main* will be installed if jupyter exists.Or the nbextension installation will be skipped. + +```shell +pip install pyecharts +``` + +In the development, you can also use the command to install manually jupyter nbextension. + +```shell +$ git clone https://github.com/pyecharts/jupyter-echarts.git +$ cd jupyter-echarts +$ jupyter nbextension install echarts --user +``` + +You can check the jupyter nbextension using the *list* command. + +```shell +$ jupyter nbextension list +Known nbextensions: + config dir: /Users/jaska/.jupyter/nbconfig + notebook section + echarts/main enabled + - Validating: OK +``` + + + +## Show Charts + +In the Notebook cell ,you can simply call the instance itself to diplay the chart. + +All chart classes in pyecharts implement the `_repr_html_` interface about [IPython Rich Display](http://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display) . + +![pandas_numpy](https://github.com/pyecharts/pyecharts/blob/master/images/pandas-numpy.png) + +## Export Images and Pdf + +You can also download as some file formats (ipynb/py/html/pdf) and run without jupyter notebook enviromnment. + +**Important** ：You must be use remote jshost mode to enable this feature. + +```python +from pyecharts import online + +online(host='https://my-site.com') +``` + +## Demo + +see more detail for [pyecharts-users-cases](https://github.com/pyecharts/pyecharts-users-cases) 。 + +## jupyterlab + +[jupyterlab](https://github.com/jupyterlab/jupyterlab) is the next generation for Jupyter Notebook,and this is a very early preview, and is not suitable for general usage yet. We will pay Continuous attention to the development and make adapter with pyecharts. + diff --git a/docs/en-us/team.md b/docs/en-us/team.md new file mode 100644 index 00000000..44623fc6 --- /dev/null +++ b/docs/en-us/team.md @@ -0,0 +1,27 @@ +# Author + +## Development Team + +Home Url: https://github.com/pyecharts + +| Avatar | Username | Role | +| ------ | ------ | ------ | +| ![chenjiandongx](https://avatars3.githubusercontent.com/u/19553554?s=60&v=4) | [chenjiandongx](https://github.com/chenjiandongx) | Owner | +| |[chfw](https://github.com/chfw) | Member | +| ![kinegratii](https://avatars2.githubusercontent.com/u/9875406?s=60&v=4) | [kinegratii](https://github.com/kinegratii) | Member | + +## Contributors + +> Thank you for contributions ！ + +| Avatar | Username | +| ------ | ------ | +| landpack | [landpack](https://github.com/landpack) | +| muxuezi | [muxuezi](https://github.com/muxuezi) | +| 647-coder | [647-coder](https://github.com/647-coder) | +| sd8089730 | [sd8089730](https://github.com/sd8089730) | +| MiracleXYZ | [MiracleXYZ](https://github.com/MiracleXYZ) | +| mowujilun | [mowujilun](https://github.com/mowujilun) | +| xbanke | [xbanke](https://github.com/xbanke) | +| shkey | [shkey](https://github.com/shkey) | +| crispgm | [crispgm](https://github.com/crispgm) | \ No newline at end of file diff --git a/docs/en-us/doc_web_integration.md b/docs/en-us/web_integration.md similarity index 100% rename from docs/en-us/doc_web_integration.md rename to docs/en-us/web_integration.md diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 00000000..5b56c9ba Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/index.html b/docs/index.html index 40b170a2..35126a13 100644 --- a/docs/index.html +++ b/docs/index.html @@ -8,14 +8,14 @@ +