You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zeppelin.apache.org by fe...@apache.org on 2016/02/06 19:57:14 UTC
incubator-zeppelin git commit: [ZEPPELIN-632][DOC] Document steps to
contribute a new interpreter
Repository: incubator-zeppelin
Updated Branches:
refs/heads/master 6e3512085 -> c484bf74e
[ZEPPELIN-632][DOC] Document steps to contribute a new interpreter
### What is this PR for?
Instead of going through a list of items one by one in PR review, we should have a checklist of TODOs for a potential interpreter contributor to review and follow
### What type of PR is it?
Documentation
### Todos
* [x] - Update doc
### Is there a relevant Jira issue?
https://issues.apache.org/jira/browse/ZEPPELIN-632
### How should this be tested?
N/A
### Screenshots (if appropriate)
N/A
### Questions:
* Does the licenses files need update? No
* Is there breaking changes for older versions? No
* Does this needs documentation? This is.
Author: Felix Cheung <fe...@hotmail.com>
Closes #675 from felixcheung/createinterpreterdoc and squashes the following commits:
0feb8fe [Felix Cheung] add link
2a4aa4b [Felix Cheung] add link to pom src
dc47a58 [Felix Cheung] small wording update
78d9127 [Felix Cheung] doc update
Project: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/commit/c484bf74
Tree: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/tree/c484bf74
Diff: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/diff/c484bf74
Branch: refs/heads/master
Commit: c484bf74efad9f0dee4f2be496bdeebb2c94c8f3
Parents: 6e35120
Author: Felix Cheung <fe...@hotmail.com>
Authored: Tue Feb 2 21:55:48 2016 -0800
Committer: Felix Cheung <fe...@apache.org>
Committed: Sat Feb 6 10:57:12 2016 -0800
----------------------------------------------------------------------
docs/development/writingzeppelininterpreter.md | 35 ++++++++++++++++-----
docs/manual/interpreters.md | 16 ++--------
2 files changed, 30 insertions(+), 21 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/c484bf74/docs/development/writingzeppelininterpreter.md
----------------------------------------------------------------------
diff --git a/docs/development/writingzeppelininterpreter.md b/docs/development/writingzeppelininterpreter.md
index dede756..ced42f8 100644
--- a/docs/development/writingzeppelininterpreter.md
+++ b/docs/development/writingzeppelininterpreter.md
@@ -23,7 +23,7 @@ limitations under the License.
Zeppelin Interpreter is a language backend. For example to use scala code in Zeppelin, you need scala interpreter.
Every Interpreter belongs to an InterpreterGroup. InterpreterGroup is a unit of start/stop interpreter.
-Interpreters in the same InterpreterGroup can reference each other. For example, SparkSqlInterpreter can reference SparkInterpreter to get SparkContext from it while they're in the same group.
+Interpreters in the same InterpreterGroup can reference each other. For example, SparkSqlInterpreter can reference SparkInterpreter to get SparkContext from it while they're in the same group.
<img class="img-responsive" style="width:50%; border: 1px solid #ecf0f1;" height="auto" src="/assets/themes/zeppelin/img/interpreter.png" />
@@ -48,6 +48,18 @@ The name of the interpreter is what you later write to identify a paragraph whic
%MyInterpreterName
some interpreter specific code...
```
+
+### Programming Languages for Interpreter
+If the interpreter uses a specific programming language ( like Scala, Python, SQL ), it is generally recommended to add a syntax highlighting supported for that to the notebook paragraph editor.
+
+To check out the list of languages supported, see the `mode-*.js` files under `zeppelin-web/bower_components/ace-builds/src-noconflict` or from [github.com/ajaxorg/ace-builds](https://github.com/ajaxorg/ace-builds/tree/master/src-noconflict).
+
+If you want to add a new set of syntax highlighting,
+
+1. Add the `mode-*.js` file to `zeppelin-web/bower.json` ( when built, `zeppelin-web/src/index.html` will be changed automatically. ).
+2. Add to the list of `editorMode` in `zeppelin-web/src/app/notebook/paragraph/paragraph.controller.js` - it follows the pattern 'ace/mode/x' where x is the name.
+3. Add to the code that checks for `%` prefix and calls `session.setMode(editorMode.x)` in `setParagraphMode` located in `zeppelin-web/src/app/notebook/paragraph/paragraph.controller.js`.
+
### Install your interpreter binary
Once you have built your interpreter, you can place it under the interpreter directory with all its dependencies.
@@ -64,7 +76,7 @@ To configure your interpreter you need to follow these steps:
Property value is comma separated [INTERPRETER\_CLASS\_NAME].
For example,
-
+
```
<property>
<name>zeppelin.interpreters</name>
@@ -79,7 +91,7 @@ To configure your interpreter you need to follow these steps:
4. In the interpreter page, click the `+Create` button and configure your interpreter properties.
Now you are done and ready to use your interpreter.
-Note that the interpreters shipped with zeppelin have a [default configuration](https://github.com/apache/incubator-zeppelin/blob/master/zeppelin-zengine/src/main/java/org/apache/zeppelin/conf/ZeppelinConfiguration.java#L397) which is used when there is no `conf/zeppelin-site.xml`.
+Note that the interpreters released with zeppelin have a [default configuration](https://github.com/apache/incubator-zeppelin/blob/master/zeppelin-zengine/src/main/java/org/apache/zeppelin/conf/ZeppelinConfiguration.java#L397) which is used when there is no `conf/zeppelin-site.xml`.
### Use your interpreter
@@ -138,15 +150,24 @@ You can only omit your interpreter group when your interpreter group is selected
codes for myintp2
```
-
-
-
### Examples
-Check some interpreters shipped by default.
+Checkout some interpreters released with Zeppelin by default.
- [spark](https://github.com/apache/incubator-zeppelin/tree/master/spark)
- [markdown](https://github.com/apache/incubator-zeppelin/tree/master/markdown)
- [shell](https://github.com/apache/incubator-zeppelin/tree/master/shell)
- [hive](https://github.com/apache/incubator-zeppelin/tree/master/hive)
+### Contributing a new Interpreter to Zeppelin releases
+
+We welcome contribution to a new interpreter. Please follow these few steps:
+
+ - First, check out the general contribution guide [here](./howtocontributewebsite.html).
+ - Follow the steps in "Make your own Interpreter" section above.
+ - Add your interpreter as in the "Configure your interpreter" section above; also add it to the example template [zeppelin-site.xml.template](https://github.com/apache/incubator-zeppelin/blob/master/conf/zeppelin-site.xml.template).
+ - Add tests! They are run by Travis for all changes and it is important that they are self-contained.
+ - Include your interpreter as a module in [`pom.xml`](https://github.com/apache/incubator-zeppelin/blob/master/pom.xml).
+ - Add documentation on how to use your interpreter under `docs/interpreter/`. Follow the Markdown style as this [example](https://github.com/apache/incubator-zeppelin/blob/master/docs/interpreter/elasticsearch.md). Make sure you list config settings and provide working examples on using your interpreter in code boxes in Markdown. Link to images as appropriate (images should go to `docs/assets/themes/zeppelin/img/docs-img/`). And add a link to your documentation in the navigation menu (`docs/_includes/themes/zeppelin/_navigation.html`).
+ - Most importantly, ensure licenses of the transitive closure of all dependencies are list in [license file](https://github.com/apache/incubator-zeppelin/blob/master/zeppelin-distribution/src/bin_license/LICENSE).
+ - Commit your changes and open a Pull Request on the project [Mirror on GitHub](https://github.com/apache/incubator-zeppelin); check to make sure Travis CI build is passing.
http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/c484bf74/docs/manual/interpreters.md
----------------------------------------------------------------------
diff --git a/docs/manual/interpreters.md b/docs/manual/interpreters.md
index c886718..8d37eac 100644
--- a/docs/manual/interpreters.md
+++ b/docs/manual/interpreters.md
@@ -25,7 +25,7 @@ The concept of Zeppelin interpreter allows any language/data-processing-backend
Currently, Zeppelin supports many interpreters such as Scala ( with Apache Spark ), Python ( with Apache Spark ), SparkSQL, Hive, Markdown, Shell and so on.
## What is Zeppelin interpreter?
-Zeppelin Interpreter is a plug-in which enables Zeppelin users to use a specific language/data-processing-backend. For example, to use scala code in Zeppelin, you need `%spark` interpreter.
+Zeppelin Interpreter is a plug-in which enables Zeppelin users to use a specific language/data-processing-backend. For example, to use Scala code in Zeppelin, you need `%spark` interpreter.
When you click the ```+Create``` button in the interpreter page, the interpreter drop-down list box will show all the available interpreters on your server.
@@ -38,21 +38,9 @@ Zeppelin interpreter setting is the configuration of a given interpreter on Zepp
## What is Zeppelin Interpreter Group?
Every Interpreter is belonged to an **Interpreter Group**. Interpreter Group is a unit of start/stop interpreter.
-By default, every interpreter is belonged to a single group, but the group might contain more interpreters. For example, spark interpreter group is including Spark support, pySpark,
-SparkSQL and the dependency loader.
+By default, every interpreter is belonged to a single group, but the group might contain more interpreters. For example, Spark interpreter group is including Spark support, pySpark, SparkSQL and the dependency loader.
Technically, Zeppelin interpreters from the same group are running in the same JVM. For more information about this, please checkout [here](../development/writingzeppelininterpreter.html).
Each interpreters is belonged to a single group and registered together. All of their properties are listed in the interpreter setting like below image.
<img src="/assets/themes/zeppelin/img/screenshots/interpreter_setting_spark.png">
-
-## Programming Languages for Interpreter
-If the interpreter uses a specific programming language ( like Scala, Python, SQL ), it is generally recommended to add a syntax highlighting supported for that to the notebook paragraph editor.
-
-To check out the list of languages supported, see the `mode-*.js` files under `zeppelin-web/bower_components/ace-builds/src-noconflict` or from [github.com/ajaxorg/ace-builds](https://github.com/ajaxorg/ace-builds/tree/master/src-noconflict).
-
-If you want to add a new set of syntax highlighting,
-
-1. Add the `mode-*.js` file to `zeppelin-web/bower.json` ( when built, `zeppelin-web/src/index.html` will be changed automatically. ).
-2. Add to the list of `editorMode` in `zeppelin-web/src/app/notebook/paragraph/paragraph.controller.js` - it follows the pattern 'ace/mode/x' where x is the name.
-3. Add to the code that checks for `%` prefix and calls `session.setMode(editorMode.x)` in `setParagraphMode` located in `zeppelin-web/src/app/notebook/paragraph/paragraph.controller.js`.