Repository: zeppelin Updated Branches: refs/heads/master 4d398ef2a -> be2020123
[DOC] Improve documents related to Helium ### What is this PR for? What I did for the documents: * Highlight codes * Follow JSON syntax * Remove white spaces And in my opinion, [here](https://zeppelin.apache.org/docs/0.8.0-SNAPSHOT/development/writingzeppelinvisualization.html#1-create-a-npm-package) is ambiguous: > "Normally, you can add any dependencies in package.json however Zeppelin > Visualization package only allows two dependencies: zeppelin-vis and > zeppelin-tabledata." Does it want to say "you can add any dependencies in package.json, but you must include two dependencies: zeppelin-vis and zeppelin-tabledata."? ### What type of PR is it? [Documentation] ### Questions: * Does the licenses files need update? NO * Is there breaking changes for older versions? NO * Does this needs documentation? NO Author: Jun Kim <i2r....@gmail.com> Closes #2236 from tae-jun/helium-doc and squashes the following commits: 63505e9 [Jun Kim] Fix ambiguous sentence 3e775cf [Jun Kim] Highlight codes, follow JSON syntax, and remove white spaces Project: http://git-wip-us.apache.org/repos/asf/zeppelin/repo Commit: http://git-wip-us.apache.org/repos/asf/zeppelin/commit/be202012 Tree: http://git-wip-us.apache.org/repos/asf/zeppelin/tree/be202012 Diff: http://git-wip-us.apache.org/repos/asf/zeppelin/diff/be202012 Branch: refs/heads/master Commit: be20201236758dbba256f6480c5c2f8b91a86ae9 Parents: 4d398ef Author: Jun Kim <i2r....@gmail.com> Authored: Mon Apr 10 19:07:40 2017 +0900 Committer: ahyoungryu <ahyoung...@apache.org> Committed: Mon Apr 17 15:57:31 2017 +0900 ---------------------------------------------------------------------- docs/development/writingzeppelinapplication.md | 16 ++++---- docs/development/writingzeppelinspell.md | 40 ++++++++++---------- .../development/writingzeppelinvisualization.md | 30 +++++++-------- 3 files changed, 42 insertions(+), 44 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zeppelin/blob/be202012/docs/development/writingzeppelinapplication.md ---------------------------------------------------------------------- diff --git a/docs/development/writingzeppelinapplication.md b/docs/development/writingzeppelinapplication.md index 59f980a..265efcf 100644 --- a/docs/development/writingzeppelinapplication.md +++ b/docs/development/writingzeppelinapplication.md @@ -91,19 +91,18 @@ In the Zeppelin notebook, run `%dev run` will connect to application running in Package file is a json file that provides information about the application. Json file contains the following information -``` +```json { - name : "[organization].[name]", - description : "Description", - artifact : "groupId:artifactId:version", - className : "your.package.name.YourApplicationClass", - resources : [ + "name" : "[organization].[name]", + "description" : "Description", + "artifact" : "groupId:artifactId:version", + "className" : "your.package.name.YourApplicationClass", + "resources" : [ ["resource.name", ":resource.class.name"], ["alternative.resource.name", ":alternative.class.name"] ], - icon : "<i class="icon"></i>" + "icon" : "<i class='icon'></i>" } - ``` #### name @@ -184,4 +183,3 @@ e.g. ``` icon: "<i class='fa fa-clock-o'></i>" ``` - http://git-wip-us.apache.org/repos/asf/zeppelin/blob/be202012/docs/development/writingzeppelinspell.md ---------------------------------------------------------------------- diff --git a/docs/development/writingzeppelinspell.md b/docs/development/writingzeppelinspell.md index 1eefe83..6393b18 100644 --- a/docs/development/writingzeppelinspell.md +++ b/docs/development/writingzeppelinspell.md @@ -23,12 +23,12 @@ limitations under the License. <div id="toc"></div> -## What is Apache Zeppelin Spell +## What is Apache Zeppelin Spell -Spell is a kind of interpreter that runs on browser not on backend. So, technically it's the frontend interpreter. +Spell is a kind of interpreter that runs on browser not on backend. So, technically it's the frontend interpreter. It can provide many benefits. -- Spell is pluggable frontend interpreter. So it can be installed and removed easily using helium registry. +- Spell is pluggable frontend interpreter. So it can be installed and removed easily using helium registry. - Every spell is written in javascript. It means you can use existing javascript libraries whatever you want. - Spell runs on browser like display system (`%html`, `%table`). In other words, every spell can be used as display system as well. @@ -57,7 +57,7 @@ For example, Use `%echo` for the Echo Spell. <img class="img-responsive" style="width:70%" src="../assets/themes/zeppelin/img/docs-img/writing_spell_using.gif" /> -## Write a new Spell +## Write a new Spell Making a new spell is similar to [Helium Visualization#write-new-visualization](./writingzeppelinvisualization.html#write-new-visualization). @@ -67,14 +67,14 @@ Making a new spell is similar to [Helium Visualization#write-new-visualization]( ### 1. Create a npm package -Create a [package.json](https://docs.npmjs.com/files/package.json) in new directory for spell. +Create a [package.json](https://docs.npmjs.com/files/package.json) in new directory for spell. - You have to add a framework called `zeppelin-spell` as a dependency to create spell ([zeppelin-spell](https://github.com/apache/zeppelin/tree/master/zeppelin-web/src/app/spell)) - Also, you can add any dependencies you want to utilise. Here's an example -``` +```json { "name": "zeppelin-echo-spell", "description": "Zeppelin Echo Spell (example)", @@ -95,7 +95,7 @@ Here's an example } ``` -### 2. Write spell using framework +### 2. Write spell using framework Here are some examples you can refer @@ -106,7 +106,7 @@ Here are some examples you can refer Now, you need to write code to create spell which processing text. -```javascript +```js import { SpellBase, SpellResult, @@ -121,8 +121,8 @@ export default class EchoSpell extends SpellBase { interpret(paragraphText) { const processed = paragraphText + '!'; - - /** + + /** * should return `SpellResult` which including `data` and `type` * default type is `TEXT` if you don't specify. */ @@ -133,7 +133,7 @@ export default class EchoSpell extends SpellBase { Here is another example. Let's say we want to create markdown spell. First of all, we should add a dependency for markdown in package.json -``` +```json // package.json "dependencies": { "markdown": "0.5.0", @@ -143,7 +143,7 @@ Here is another example. Let's say we want to create markdown spell. First of al And here is spell code. -```javascript +```js import { SpellBase, SpellResult, @@ -171,16 +171,16 @@ export default class MarkdownSpell extends SpellBase { } ``` -- You might want to manipulate DOM directly (e.g google d3.js), then refer [Flowchart Spell](https://github.com/apache/zeppelin/blob/master/zeppelin-examples/zeppelin-example-spell-flowchart/index.js) +- You might want to manipulate DOM directly (e.g google d3.js), then refer [Flowchart Spell](https://github.com/apache/zeppelin/blob/master/zeppelin-examples/zeppelin-example-spell-flowchart/index.js) - You might want to return promise not string (e.g API call), then refer [Google Translation API Spell](https://github.com/apache/zeppelin/blob/master/zeppelin-examples/zeppelin-example-spell-translator/index.js) -### 3. Create __Helium package file__ for local deployment +### 3. Create __Helium package file__ for local deployment You don't want to publish your package every time you make a change in your spell. Zeppelin provides local deploy. -The only thing you need to do is creating a __Helium Package file__ (JSON) for local deploy. +The only thing you need to do is creating a __Helium Package file__ (JSON) for local deploy. It's automatically created when you publish to npm repository but in local case, you should make it by yourself. -``` +```json { "type" : "SPELL", "name" : "zeppelin-echo-spell", @@ -197,18 +197,18 @@ It's automatically created when you publish to npm repository but in local case, - Place this file in your local registry directory (default `$ZEPPELIN_HOME/helium`). - `type` should be `SPELL` -- Make sure that `artifact` should be same as your spell directory. +- Make sure that `artifact` should be same as your spell directory. - You can get information about other fields in [Helium Visualization#3-create-helium-package-file-and-locally-deploy](./writingzeppelinvisualization.html#3-create-helium-package-file-and-locally-deploy). ### 4. Run in dev mode -``` +```bash cd zeppelin-web -yarn run dev:helium +yarn run dev:helium ``` You can browse localhost:9000. Every time refresh your browser, Zeppelin will rebuild your spell and reload changes. -### 5. Publish your spell to the npm repository +### 5. Publish your spell to the npm repository See [Publishing npm packages](https://docs.npmjs.com/getting-started/publishing-npm-packages) http://git-wip-us.apache.org/repos/asf/zeppelin/blob/be202012/docs/development/writingzeppelinvisualization.md ---------------------------------------------------------------------- diff --git a/docs/development/writingzeppelinvisualization.md b/docs/development/writingzeppelinvisualization.md index 5a0601f..18b686c 100644 --- a/docs/development/writingzeppelinvisualization.md +++ b/docs/development/writingzeppelinvisualization.md @@ -61,11 +61,11 @@ User can use just like any other built-in visualizations. #### 1. Create a npm package -Create a [package.json](https://docs.npmjs.com/files/package.json) in your new Visualization directory. Normally, you can add any dependencies in package.json however Zeppelin Visualization package only allows two dependencies: [zeppelin-vis](https://github.com/apache/zeppelin/tree/master/zeppelin-web/src/app/visualization) and [zeppelin-tabledata](https://github.com/apache/zeppelin/tree/master/zeppelin-web/src/app/tabledata). +Create a [package.json](https://docs.npmjs.com/files/package.json) in your new Visualization directory. You can add any dependencies in package.json, but you **must include two dependencies: [zeppelin-vis](https://github.com/apache/zeppelin/tree/master/zeppelin-web/src/app/visualization) and [zeppelin-tabledata](https://github.com/apache/zeppelin/tree/master/zeppelin-web/src/app/tabledata).** Here's an example -``` +```json { "name": "zeppelin_horizontalbar", "description" : "Horizontal Bar chart", @@ -86,7 +86,7 @@ To create your own visualization, you need to create a js file and import [Visua [Visualization](https://github.com/apache/zeppelin/blob/master/zeppelin-web/src/app/visualization/visualization.js) class, there're several methods that you need to override and implement. Here's simple visualization that just prints `Hello world`. -``` +```js import Visualization from 'zeppelin-vis' import PassthroughTransformation from 'zeppelin-tabledata/passthrough' @@ -118,7 +118,7 @@ Zeppelin's built-in visualization uses the same API, so you can check [built-in __Helium Package file__ is a json file that provides information about the application. Json file contains the following information -``` +```json { "type" : "VISUALIZATION", "name" : "zeppelin_horizontalbar", @@ -154,15 +154,15 @@ e.g. When artifact exists in npm repository -``` -artifact: "my-visualiztion@1.0.0" +```json +"artifact": "my-visualiztion@1.0.0" ``` When artifact exists in local file system -``` -artifact: "/path/to/my/visualization" +```json +"artifact": "/path/to/my/visualization" ``` ##### license @@ -171,8 +171,8 @@ License information. e.g. -``` -license: "Apache-2.0" +```json +"license": "Apache-2.0" ``` ##### icon @@ -181,8 +181,8 @@ Icon to be used in visualization select button. String in this field will be ren e.g. -``` -icon: "<i class='fa fa-coffee'></i>" +```json +"icon": "<i class='fa fa-coffee'></i>" ``` @@ -191,9 +191,9 @@ icon: "<i class='fa fa-coffee'></i>" Place your __Helium package file__ in local registry (ZEPPELIN_HOME/helium). Run Zeppelin. And then run zeppelin-web in visualization dev mode. -``` +```bash cd zeppelin-web -yarn run dev:helium +yarn run dev:helium ``` You can browse localhost:9000. Everytime refresh your browser, Zeppelin will rebuild your visualization and reload changes. @@ -202,4 +202,4 @@ You can browse localhost:9000. Everytime refresh your browser, Zeppelin will reb #### 5. Publish your visualization Once it's done, publish your visualization package using `npm publish`. -That's it. With in an hour, your visualization will be available in Zeppelin's helium menu. \ No newline at end of file +That's it. With in an hour, your visualization will be available in Zeppelin's helium menu.
