[ZEPPELIN-1346] Add contribution guidelines to the website

_includes/sub-views/community/contribute.md

@@ -0,0 +1,41 @@
+<!--
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## How to contribute
+
+There are multiple ways you can contribute to the project.
+And help is always welcome!
+
+### Issue Tracker
+
+Apache Zeppelin uses JIRA as an [Issue Tracker](https://issues.apache.org/jira/browse/ZEPPELIN).
+Don't hesitate to report new bugs and improvements ideas.
+
+#### Contribute to the source code
+
+We like to get code contributions through Pull Requests on our [Github Mirror](https://github.com/apache/zeppelin).
+
+But before starting, please read our [Contribution guidelines](/contribution/general.html), it will give
+you important information about our review process, and pointers on how to make a good code contribution.
+
+You can visit our [Issue Tracker](https://issues.apache.org/jira/browse/ZEPPELIN) to find issues to resolve,
+and if your are a newcomer and don't know where to get started, we have set some [beginner issues](https://issues.apache.org/jira/browse/ZEPPELIN-1245?jql=project%20%3D%20ZEPPELIN%20AND%20status%20%3D%20Open%20AND%20labels%20%3D%20beginner).
+
+#### Other contributions
+
+Not much of a coder? There are other ways to help out:
+
+* Documentation and website improvements are always welcome
+* Helping each other by answering questions on the Mailing List
+* Participating in reviewing contributions.

_includes/sub-views/community/mailinglist.md

@@ -0,0 +1,27 @@
+<!--
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+## Mailing list
+
+Get help using Apache Zeppelin or contribute to the project on our mailing lists:
+
+* __Users :__ [subscribe](mailto:users-subscribe@zeppelin.apache.org?subject=send this email to subscribe),     [unsubscribe](mailto:users-unsubscribe@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-users/)
+<br/>
+for usage questions, help, and announcements.
+* __Dev :__ [subscribe](mailto:dev-subscribe@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:dev-unsubscribe@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-dev/)
+<br/>
+for people wanting to contribute to the project.
+* __Commits :__ [subscribe](mailto:commits-subscribe@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:commits-unsubscribe@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-commits/)
+<br/>
+for commit messages and patches.

_includes/themes/zeppelin/sideMenu.html

@@ -0,0 +1,16 @@
+<div class="row">
+  {% if page.menu %}
+    <div class="sideMenu col-md-3">
+      {% assign pages_list = site.pages %}
+      {% assign group = page.menu %}
+      {% include JB/pages_list %}
+    </div>
+    <div class="col-md-9">
+      {{ content }}
+    </div>
+  {% else %}
+    <div class="col-md-12">
+      {{ content }}
+    </div>
+  {% endif %}
+</div>

_layouts/sideMenu.html

@@ -0,0 +1,5 @@
+---
+layout: default
+---
+{% include JB/setup %}
+{% include themes/zeppelin/sideMenu.html %}

_plugins/markdown_tag.rb

@@ -0,0 +1,23 @@
+=begin
+  Jekyll tag to include Markdown text from _includes directory preprocessing with Liquid.
+  Usage:
+    {% markdown <filename> %}
+  Dependency:
+    - kramdown
+=end
+module Jekyll
+  class MarkdownTag < Liquid::Tag
+    def initialize(tag_name, text, tokens)
+      super
+      @text = text.strip
+    end
+    require "kramdown"
+    def render(context)
+      tmpl = File.read File.join Dir.pwd, "_includes", @text
+      site = context.registers[:site]
+      tmpl = (Liquid::Template.parse tmpl).render site.site_payload
+      html = Kramdown::Document.new(tmpl).to_html
+    end
+  end
+end
+Liquid::Template.register_tag('markdown', Jekyll::MarkdownTag)

assets/themes/zeppelin/css/style.css

@@ -173,6 +173,31 @@ body {
   outline-width: 0;
 }
 
+/* SideMenu */
+
+.sideMenu li {
+  list-style: none;
+  border: 1px solid #c2c2c2;
+  border-bottom: none;
+  padding: 5px 10px;
+}
+
+.sideMenu li a {
+  text-decoration: none;
+  color: #3071a9;
+}
+
+.sideMenu li:first-of-type {
+  border-top-left-radius: 3px;
+  border-top-right-radius: 3px;
+}
+
+.sideMenu li:last-of-type {
+  border-bottom: 1px solid #c2c2c2;
+  border-bottom-left-radius: 3px;
+  border-bottom-right-radius: 3px;
+}
+
 /* CUSTOMIZE THE CAROUSEL
 -------------------------------------------------- */
 

community.md

@@ -19,15 +19,11 @@ limitations under the License.
 -->
 {% include JB/setup %}
 
-
-### Mailing list
-
-Get help using Apache Zeppelin or contribute to the project on our mailing lists:
-
-* [users@zeppelin.apache.org](http://mail-archives.apache.org/mod_mbox/zeppelin-users/) is for usage questions, help, and announcements. [subscribe](mailto:users-subscribe@zeppelin.apache.org?subject=send this email to subscribe),     [unsubscribe](mailto:users-unsubscribe@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-users/)
-* [dev@zeppelin.apache.org](http://mail-archives.apache.org/mod_mbox/zeppelin-dev/) is for people who want to contribute code to Zeppelin. [subscribe](mailto:dev-subscribe@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:dev-unsubscribe@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-dev/)
-* [commits@zeppelin.apache.org](http://mail-archives.apache.org/mod_mbox/zeppelin-commits/) is for commit messages and patches to Zeppelin. [subscribe](mailto:commits-subscribe@zeppelin.apache.org?subject=send this email to subscribe), [unsubscribe](mailto:commits-unsubscribe@zeppelin.apache.org?subject=send this email to unsubscribe), [archives](http://mail-archives.apache.org/mod_mbox/zeppelin-commits/)
-
-### Issue tracker
-
-  [https://issues.apache.org/jira/browse/ZEPPELIN](https://issues.apache.org/jira/browse/ZEPPELIN)
+<div class="row">
+  <div class="col-md-6">
+    {% markdown sub-views/community/contribute.md %}
+  </div>
+  <div class="col-md-6">
+    {% markdown sub-views/community/mailinglist.md %}
+  </div>
+</div>

contribution/documentation.md

@@ -0,0 +1,170 @@
+---
+layout: sideMenu
+title: "Documentation"
+description: ""
+group: nav-contrib
+---
+<!--
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Contributing to Documentation
+
+## Dev Mode
+Apache Zeppelin is using [Jekyll](https://jekyllrb.com/) which is a static site generator and [Github Pages](https://pages.github.com/) as a site publisher. For the more details, see [help.github.com/articles/about-github-pages-and-jekyll/](https://help.github.com/articles/about-github-pages-and-jekyll/).
+
+### Requirements
+
+```
+# ruby --version >= 2.0.0
+# Install Bundler using gem
+gem install bundler
+
+cd $ZEPPELIN_HOME/docs
+# Install all dependencies declared in the Gemfile
+bundle install
+```
+
+For the further information about requirements, please see [here](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/#requirements).
+
+On OS X 10.9, you may need to do 
+
+```
+xcode-select --install
+
+```
+### Run the website locally
+
+If you don't want to encounter uglily rendered pages, run the documentation site in your local first.
+In `$ZEPPELIN_HOME/docs`,
+
+```
+bundle exec jekyll serve --watch
+```
+
+Using the above command, Jekyll will start a web server at `http://localhost:4000` and watch the `/docs` directory to update.
+
+
+## Folder Structure & Components
+`docs/` folder is organized like below:
+
+```
+docs/
+ ├── _includes/themes/zeppelin 
+ │   ├── _navigation.html
+ │   └── default.html
+ ├── _layouts
+ ├── _plugins
+ ├── assets/themes/zeppelin -> {ASSET_PATH}
+ │    ├── bootstrap
+ │    ├── css
+ │    ├── img
+ │    └── js
+ ├── development/ *.md
+ ├── displaysystem/ *.md
+ ├── install/ *.md
+ ├── interpreter/ *.md
+ ├── manual/ *.md
+ ├── quickstart/ *.md
+ ├── rest-api/ *.md
+ ├── security/ *.md
+ ├── storage/ *.md
+ ├── Gemfile
+ ├── Gemfile.lock
+ ├── _config.yml
+ ├── index.md
+ └── ...
+```
+
+ - `_navigation.html`: the dropdown menu in navbar
+ - `default.html` & `_layouts/`: define default HTML layout
+ - `_plugins/`: custom plugin `*.rb` files can be placed in this folder. See [jekyll/plugins](https://jekyllrb.com/docs/plugins/) for the further information.
+ - `{ASSET_PATH}/css/style.css`: extra css components can be defined
+ - `{ASSET_PATH}/img/docs-img/`: image files used for document pages can be placed in this folder
+ - `{ASSET_PATH}/js/`: extra `.js` files can be placed
+ - `Gemfile`: defines bundle dependencies. They will be installed by `bundle install`.
+ - `Gemfile.lock`: when you run `bundle install`, bundler will persist all gems name and their version to this file. For the more details, see [Bundle "The Gemfile Lock"](http://bundler.io/v1.10/man/bundle-install.1.html#THE-GEMFILE-LOCK)
+ - `documentation_group`: `development/`, `displaysystem/`, `install/`, `interpreter/`...
+ - `_config.yml`: defines configuration options for docs website. See [jekyll/configuration](https://jekyllrb.com/docs/configuration/) for the other available config variables.
+ - `index.md`: the main page of `http://zeppelin.apache.org/docs/<ZEPPELIN_VERSION>/`
+
+
+### Markdown
+Zeppelin documentation pages are written with [Markdown](http://daringfireball.net/projects/markdown/). It is possible to use [GitHub flavored syntax](https://help.github.com/categories/writing-on-github/) and intermix plain HTML.
+
+### Front matter
+Every page contains [YAML front matter](https://jekyllrb.com/docs/frontmatter/) block in their header. Don't forget to wrap the front matter list with triple-dashed lines(`---`) like below.
+The document page should start this triple-dashed lines. Or you will face 404 error, since Jekyll can't find the page.
+
+```
+---
+layout: page
+title: "Apache Zeppelin Tutorial"
+description: "This tutorial page contains a short walk-through tutorial that uses Apache Spark backend. Please note that this tutorial is valid for Spark 1.3 and higher."
+group: quickstart
+---
+```
+
+ - `layout`: the default layout is `page` which is defined in `_layout/page.html`.
+ - `title`: the title for the document. Please note that if it needs to include `Zeppelin`, it should be `Apache Zeppelin`, not `Zeppelin`.
+ - `description`: a short description for the document. One or two sentences would be enough. This description also will be shown as an extract sentence when people search pages.
+ - `group`: a category of the document page
+
+### Headings
+All documents are structured with headings. From these headings, you can automatically generate a **Table of Contents**. There is a simple rule for Zeppelin docs headings.
+
+```
+#    Level-1 heading <- used only for the main title
+##   Level-2 heading <- start with this
+###  Level-3 heading 
+#### Level-4 heading <- won't be converted in TOC from this level
+```
+
+### Table of contents(TOC)
+
+```
+<div id="toc"></div>
+```
+
+Add this line below  `# main title` in order to generate a **Table of Contents**. Headings until `### (Level-3 heading)` are included to TOC.
+
+
+Default setting options for TOC are definded in [here](https://github.com/apache/zeppelin/blob/master/docs/assets/themes/zeppelin/js/toc.js#L4).
+
+
+### Adding new pages
+If you're going to create new pages, there are some spots you need to add the location of the page.
+
+ - **Dropdown menu in navbar**: add your docs location to [_navigation.html](https://github.com/apache/zeppelin/blob/master/docs/_includes/themes/zeppelin/_navigation.html)
+ - **Main index**: add your docs below [What is the next?](http://zeppelin.apache.org/docs/latest/#what-is-the-next) section in [index.md](https://github.com/apache/zeppelin/blob/master/docs/index.md) with a short description. No need to do this if the page is for **Interpreters**.
+
+
+## For committers only
+### Bumping up version in a new release
+
+`ZEPPELIN_VERSION` and `BASE_PATH` property in `_config.yml`
+
+### Deploy to ASF svnpubsub infra
+ 1. generate static website in `./_site`
+
+    ```
+    # go to /docs under Zeppelin source
+    bundle exec jekyll build --safe
+    ```
+
+ 2. checkout ASF repo
+    ```
+    svn co https://svn.apache.org/repos/asf/zeppelin asf-zeppelin
+    ```
+ 3. copy `zeppelin/docs/_site` to `asf-zeppelin/site/docs/[VERSION]`
+ 4. ```svn commit```