diff --git a/README.md b/README.md index 978047b724..ed49b8c44d 100644 --- a/README.md +++ b/README.md @@ -48,12 +48,12 @@ Kepler.gl is also a React component that uses [Redux](https://redux.js.org/) to ## Env -Use Node v6 and above, older node versions have not been tested. +Use Node 8.15.0 and above, older node versions have not been tested. For best results, use [nvm](https://github.com/creationix/nvm) `nvm install`. ## Install kepler.gl -Install node (`> 6`), yarn, and project dependencies +Install node (`> 8.15.0`), yarn, and project dependencies ```sh npm install --save kepler.gl diff --git a/bindings/kepler.gl-jupyter/README.md b/bindings/kepler.gl-jupyter/README.md index 925bdba95e..32b7a11390 100644 --- a/bindings/kepler.gl-jupyter/README.md +++ b/bindings/kepler.gl-jupyter/README.md @@ -10,12 +10,17 @@ This is the [kepler.gl](http://kepler.gl) jupyter widget, an advanced geospatial - [Demo Notebooks](#demo-notebooks) - [Usage](#usage) - [Local Development Setup](#local-development-setup) +- [FAQ & Troubleshoot](#faq--troubleshoot)

# Installation ------------- + +### Prerequisites +- Python >= 2 +- ipywidgets >= 7.0.0 + To install use pip: @@ -28,6 +33,21 @@ If you on Mac used `pip install` and running Notebook 5.3 and above, you don't n $ jupyter nbextension enable --py --sys-prefix keplergl # can be skipped for notebook 5.3 and above +If you arr in JupyterLab, you will also need to install the JupyterLab extension. This require [node](https://nodejs.org/en/download/package-manager/#macos) `> 8.15.0` + +If you use [Homebrew](https://brew.sh/) on Mac: + + $ brew install node@8 + +Then install jupyter labextension. + + $ jupyter labextension install @jupyter-widgets/jupyterlab-manager keplergl-jupyter + +**Prerequisites for JupyterLab:** +- Node > 8.15.0 +- Python 3 +- JupyterLab>=1.0.0 +

# Quick Start @@ -89,7 +109,8 @@ map_1.save_to_html(file_name='keplergl_map.html') You will need to install node, yarn and Jupyter Notebook. ### 1. Node and Yarn -Install [node](https://nodejs.org/en/download/package-manager/#macos) (`> 8`), and [yarn](https://yarnpkg.com/en/docs/install#mac-stable) +Install [node](https://nodejs.org/en/download/package-manager/#macos) `> 8.15.0`, and [yarn](https://yarnpkg.com/en/docs/install#mac-stable). Use [nvm](https://github.com/creationix/nvm) for better node version management e.g. `nvm install 8`. + ### 2. Install Jupyter with pip @@ -148,11 +169,64 @@ This command must be run **AFTER** the `js` setup, and folder `static/` was crea $ cd notebooks $ jupyter notebook + + ### Have fun! You can now start editing the .js and .py files to see changes reflected in your local notebook. After changing files in the js folder, the local start script will recompile the js files and put them in to `keplergl/static` folder. You need to reload the jupyter notebook page to reload the files. +# FAQ & Troubleshoot + +#### 1. What about windows? +keplergl is currently only published to PyPI, and unfortunately I use a Mac. If you encounter errors installing it on windows. [This issue](https://github.com/keplergl/kepler.gl/issues/557) might shed some light. Follow this issue for [conda](https://github.com/keplergl/kepler.gl/issues/646) support. + +#### 2. Install keplergl-jupyter on Jupyter Lab failed? + +Make sure you are using node 8.15.0. and you have installed `@jupyter-widgets/jupyterlab-manager`. Depends on your JupyterLab version. You might need to install the specific version of [jupyterlab-manager](https://github.com/jupyter-widgets/ipywidgets/tree/master/packages/jupyterlab-manager). with `jupyter labextension install @jupyter-widgets/jupyterlab-manager@0.31`. When use it in Jupyter lab, keplergl is only supported in JupyterLab > 1.0 and Python 3. + +Run `jupyter labextension install keplergl-jupyter --debug` and copy console output before creating an issue. + +If you are running `install` and `uninstall` several times. You should run. +``` +jupyter lab clean +jupyter lab build +``` + +#### 2.1 JavaScript heap out of memory when installing lab extension +If you see this error during install labextension + + $ FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory +run + + $ export NODE_OPTIONS=--max-old-space-size=4096 + +#### 3. Is my lab extension successfully installed? +Run `jupyter labextension list` You should see below. (Version may vary) +```sh +JupyterLab v1.1.4 +Known labextensions: + app dir: /Users/xxx/jupyter-python3/ENV3/share/jupyter/lab + @jupyter-widgets/jupyterlab-manager v1.0.2 enabled OK + keplergl-jupyter v0.1.0 enabled OK +``` + +#### 4. What's your python and node env + +Python +``` +python==3.7.4 +notebook==6.0.1 +jupyterlab==1.1.4 +ipywidgets==7.5.1 +``` + +Node (Only for JupyterLab) +``` +node==8.15.0 +yarn==1.7.0 +``` + [jupyter_widget]: https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/jupyter_widget.png [empty_map]: https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/jupyter_empty_map.png [geodataframe_map]: https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/jupyter_geodataframe.png diff --git a/bindings/kepler.gl-jupyter/RELEASE.md b/bindings/kepler.gl-jupyter/RELEASE.md index 4b4d979415..cc9a35c896 100644 --- a/bindings/kepler.gl-jupyter/RELEASE.md +++ b/bindings/kepler.gl-jupyter/RELEASE.md @@ -1,22 +1,36 @@ -- To release a new version of keplergl on PyPI: -Update _version.py (set release version, remove 'dev') -git add the _version.py file and git commit -change version in first_widget/_version.py -`rm -r dist` -`python setup.py sdist` -`twine upload dist/*` +## Release a new version -Update _version.py (add 'dev' and increment minor) -git add and git commit -git push -git push --tags +To release a new version. You need publish both the js module in NPM and the python module on PyPI. +Version number of the js module **`kelergl-jupyter`** and the python module **`keplergl`** should match -- To release a new version of keplergl-jupyter on NPM: +### To release a new version of keplergl-jupyter on NPM: +- Edit version number in `js/package.json` ``` -# clean out the `dist` and `node_modules` directories -git clean -fdx -npm install +git commit -am "keplergl-jupyter@" +npm login npm publish ``` + +### To release a new version of keplergl on PyPI: + +- Update version number in _version.py + +``` +git add _version.py +git commit -am "keplergl== +``` + +- Remove dist, build and upload to PyPI +``` +rm -r dist +python setup.py sdist +twine upload dist/* +``` + +### add tags +``` +git tag -a -jupyter -m "-jupyter +git push origin master && git push origin -jupyter +``` diff --git a/bindings/kepler.gl-jupyter/js/.babelrc b/bindings/kepler.gl-jupyter/js/.babelrc index 88b9f2cbb0..2bad34aa6c 100644 --- a/bindings/kepler.gl-jupyter/js/.babelrc +++ b/bindings/kepler.gl-jupyter/js/.babelrc @@ -25,10 +25,10 @@ "proposal": "minimal" } ], + "@babel/plugin-transform-react-jsx", + "transform-inline-environment-variables", "@babel/plugin-proposal-nullish-coalescing-operator", "@babel/plugin-proposal-do-expressions", - "@babel/plugin-proposal-function-bind", - "@babel/plugin-transform-modules-commonjs", - ["inline-json-import", {}] + "@babel/plugin-proposal-function-bind" ] } diff --git a/bindings/kepler.gl-jupyter/js/.gitignore b/bindings/kepler.gl-jupyter/js/.gitignore index cd249d7348..8e1dcff08d 100644 --- a/bindings/kepler.gl-jupyter/js/.gitignore +++ b/bindings/kepler.gl-jupyter/js/.gitignore @@ -2,6 +2,7 @@ node_modules/ dist/ temp.* keplergl/ +babel/ yarn.lock yarn-error.log diff --git a/bindings/kepler.gl-jupyter/js/README.md b/bindings/kepler.gl-jupyter/js/README.md index 849cc110c2..c0cb61dbbc 100644 --- a/bindings/kepler.gl-jupyter/js/README.md +++ b/bindings/kepler.gl-jupyter/js/README.md @@ -1,10 +1,12 @@ +# kperlgl-jupyter + This is a simple jupyter widget for kepler.gl, an advanced geospatial visualization tool, to render large-scale interactive maps. Package Install --------------- **Prerequisites** -- [node](http://nodejs.org/) >=8.1.0 +- [node](http://nodejs.org/) >=8.15.0 - [yarn](https://yarnpkg.com/en/docs/install#mac-stable) >=1.6.0 **More links** diff --git a/bindings/kepler.gl-jupyter/js/lib/keplergl-plugin.js b/bindings/kepler.gl-jupyter/js/lib/keplergl-plugin.js index 53d0261a0e..cb96245419 100644 --- a/bindings/kepler.gl-jupyter/js/lib/keplergl-plugin.js +++ b/bindings/kepler.gl-jupyter/js/lib/keplergl-plugin.js @@ -18,7 +18,7 @@ // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN // THE SOFTWARE. -import widgets from '@jupyter-widgets/base'; +import * as widgets from '@jupyter-widgets/base'; import KeplerGlJupyter from './keplergl/kepler.gl'; import log from './log'; @@ -45,8 +45,6 @@ export const KeplerGlModal = widgets.DOMWidgetModel.extend({ _view_name: 'KeplerGlView', _model_module: 'keplergl-jupyter', _view_module: 'keplergl-jupyter', - _model_module_version: '0.1.0', - _view_module_version: '0.1.0', data: {}, config: {} diff --git a/bindings/kepler.gl-jupyter/js/package.json b/bindings/kepler.gl-jupyter/js/package.json index 88a1131d31..57432a690e 100644 --- a/bindings/kepler.gl-jupyter/js/package.json +++ b/bindings/kepler.gl-jupyter/js/package.json @@ -3,21 +3,29 @@ "version": "0.1.0", "description": "This is a simple jupyter widget for kepler.gl, an advanced geo-spatial visualization tool, to render large-scale interactive maps.", "author": "Shan He", - "main": "lib/index.js", + "license": "MIT", + "main": "babel/index.js", + "engines": { + "node": ">=8.15.0", + "npm": ">=6.1.0", + "yarn": ">=1.6.0" + }, "repository": { "type": "git", "url": "https://github.com/keplergl/kepler.gl.git" }, "keywords": [ "jupyter", + "jupyterlab", + "jupyterlab-extension", "widgets", "ipython", - "ipywidgets", - "jupyterlab-extension" + "ipywidgets" ], "files": [ "lib/**/*.js", - "dist/*.js" + "dist/*.js", + "babel/**" ], "scripts": { "start": "NODE_ENV=development webpack --config ./webpack/dev.js --mode development --watch --progress", @@ -25,14 +33,16 @@ "cleanall": "npm run clean && rimraf node_modules/", "check-licence": "uber-licence --dry", "add-licence": "uber-licence", - "prepublish": "uber-licence && yarn build", + "prepublish": "uber-licence && yarn build && yarn build:lab", "build": "npm run clean && uber-licence && webpack --config ./webpack/build.js", + "build:lab": "rimraf babel/ && mkdir babel && babel lib --out-dir babel", "test": "echo \"Error: no test specified\" && exit 1", "lint": "eslint lib webpack --fix", "prettier": "prettier --config ./.prettierrc --print-width 80 --single-quote --write lib/**/*.js" }, "devDependencies": { - "@babel/core": "^7.0.0", + "@babel/cli": "7.4.4", + "@babel/core": "7.4.5", "@babel/plugin-proposal-class-properties": "^7.3.0", "@babel/plugin-proposal-decorators": "^7.3.0", "@babel/plugin-proposal-do-expressions": "^7.0.0", @@ -50,6 +60,7 @@ "@babel/plugin-syntax-dynamic-import": "^7.0.0", "@babel/plugin-syntax-import-meta": "^7.0.0", "@babel/plugin-transform-modules-commonjs": "^7.2.0", + "@babel/plugin-transform-react-jsx": "7.3.0", "@babel/plugin-transform-runtime": "^7.0.0", "@babel/preset-env": "^7.0.0", "@babel/preset-react": "^7.0.0", @@ -58,6 +69,7 @@ "babel-plugin-inline-json-import": "^0.2.1", "babel-plugin-module-resolver": "^3.0.0", "babel-plugin-transform-builtin-extend": "^1.1.0", + "babel-plugin-transform-inline-environment-variables": "0.4.3", "eslint": "^5.12.1", "eslint-config-prettier": "^3.6.0", "eslint-config-uber-es2015": "^3.1.2", @@ -78,7 +90,7 @@ "webpack-stats-plugin": "^0.2.1" }, "dependencies": { - "@jupyter-widgets/base": "^1.0.0", + "@jupyter-widgets/base": "^1.1.10 || ^2", "global": "^4.3.0", "kepler.gl": "^1.1.8", "react": "^16.8.4", @@ -91,6 +103,6 @@ "uber-licence": "^3.1.1" }, "jupyterlab": { - "extension": "lib/labplugin" + "extension": "babel/labplugin" } } diff --git a/bindings/kepler.gl-jupyter/js/webpack/config.js b/bindings/kepler.gl-jupyter/js/webpack/config.js index 48d615e6db..20ba9d36d9 100644 --- a/bindings/kepler.gl-jupyter/js/webpack/config.js +++ b/bindings/kepler.gl-jupyter/js/webpack/config.js @@ -101,7 +101,7 @@ module.exports = { filename: 'index.js', path: path.resolve(__dirname, '../dist'), libraryTarget: 'amd', - publicPath: `https://unpkg.com/keplergl-jupyter@${ version }/dist/` + publicPath: `https://unpkg.com/keplergl-jupyter@${version}/dist/` }, mode: 'production', module: { diff --git a/bindings/kepler.gl-jupyter/keplergl/_version.py b/bindings/kepler.gl-jupyter/keplergl/_version.py index 15277f23cd..b4c3975086 100644 --- a/bindings/kepler.gl-jupyter/keplergl/_version.py +++ b/bindings/kepler.gl-jupyter/keplergl/_version.py @@ -1,4 +1,4 @@ -version_info = (0, 1, 0, 'alpha', 9) +version_info = (0, 1, 0, 'final', 0) _specifier_ = {'alpha': 'a', 'beta': 'b', 'candidate': 'rc', 'final': ''} diff --git a/bindings/kepler.gl-jupyter/notebooks/DataFrame.ipynb b/bindings/kepler.gl-jupyter/notebooks/DataFrame.ipynb index 257dd3d32a..b5f47974e9 100644 --- a/bindings/kepler.gl-jupyter/notebooks/DataFrame.ipynb +++ b/bindings/kepler.gl-jupyter/notebooks/DataFrame.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "code", - "execution_count": 16, + "execution_count": 1, "metadata": {}, "outputs": [], "source": [ @@ -11,7 +11,7 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 2, "metadata": {}, "outputs": [], "source": [ @@ -26,7 +26,7 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 3, "metadata": {}, "outputs": [], "source": [ @@ -71,7 +71,7 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 4, "metadata": {}, "outputs": [ { @@ -84,7 +84,7 @@ { "data": { "application/vnd.jupyter.widget-view+json": { - "model_id": "9d929324ad044aad87c3aca238549d47", + "model_id": "94e4cf1bad504cb2b2001960a45743ae", "version_major": 2, "version_minor": 0 }, @@ -140,5 +140,5 @@ } }, "nbformat": 4, - "nbformat_minor": 2 + "nbformat_minor": 4 } diff --git a/bindings/kepler.gl-jupyter/setup.py b/bindings/kepler.gl-jupyter/setup.py index 17ebb2f8be..7f5e720c67 100644 --- a/bindings/kepler.gl-jupyter/setup.py +++ b/bindings/kepler.gl-jupyter/setup.py @@ -22,7 +22,7 @@ log.info('setup.py entered') log.info('$PATH=%s' % os.environ['PATH']) -LONG_DESCRIPTION = 'This is a simple jupyter widget for kepler.gl, an advanced geospatial visualization tool, to render large-scale interactive maps.' +LONG_DESCRIPTION = 'A jupyter widget for kepler.gl, an advanced geospatial visualization tool, to render large-scale interactive maps.' def js_prerelease(command, strict=False): """decorator for building minified js/css prior to another command""" @@ -135,7 +135,7 @@ def run(self): 'keplergl/static/extension.js', 'keplergl/static/index.js', 'keplergl/static/index.js.map', - ],), + ]), ('etc/jupyter/nbconfig/notebook.d' ,['keplergl-jupyter.json']) ], 'install_requires': [ @@ -161,6 +161,9 @@ def run(self): 'ipython', 'jupyter', 'widgets', + 'geospatial', + 'visualization', + 'webGL' ], 'classifiers': [ 'Development Status :: 4 - Beta', diff --git a/package.json b/package.json index 0cc3fbc4f0..9e9f46a8eb 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "license": "MIT", "main": "dist/index.js", "engines": { - "node": ">=8.7.0", + "node": ">=8.15.0", "npm": ">=6.1.0", "yarn": ">=1.6.0" },