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/08/19 06:42:14 UTC
zeppelin git commit: [ZEPPELIN-1323] Add contribution guide for
Zeppelin documentation
Repository: zeppelin
Updated Branches:
refs/heads/master 49b3df666 -> ff2465b9d
[ZEPPELIN-1323] Add contribution guide for Zeppelin documentation
### What is this PR for?
Recently I added auto generated Table of Contents by #1031 and searching feature by #1266. So I wrote some guide to `docs/CONTRIBUTING.md` about how to use and how they can be applied to docs page. Hope this helps to new Zeppelin (docs) contributors :)
### What type of PR is it?
Documentation
### Todos
* [x] - Update `docs/README.md`
### What is the Jira issue?
[ZEPPELIN-1323](https://issues.apache.org/jira/browse/ZEPPELIN-1323)
### How should this be tested?
Just click `View` button on the top of the file diff :)
### Screenshots (if appropriate)
### Questions:
* Does the licenses files need update? no
* Is there breaking changes for older versions? no
* Does this needs documentation? no
Author: AhyoungRyu <fb...@hanmail.net>
Closes #1326 from AhyoungRyu/ZEPPELIN-1323 and squashes the following commits:
e23286b [AhyoungRyu] Update some contents
f74c676 [AhyoungRyu] Attach 'Apache' to the title in README.md
f1eb6b3 [AhyoungRyu] Change Zeppelin docs link version to latest
2879ada [AhyoungRyu] Exclude docs/CONTRIBUTING.md
2f7520b [AhyoungRyu] Remove useless back slash
b58183b [AhyoungRyu] Add new files: CONTRIBUTING.md
3c05b47 [AhyoungRyu] Update contents in docs/README.md
Project: http://git-wip-us.apache.org/repos/asf/zeppelin/repo
Commit: http://git-wip-us.apache.org/repos/asf/zeppelin/commit/ff2465b9
Tree: http://git-wip-us.apache.org/repos/asf/zeppelin/tree/ff2465b9
Diff: http://git-wip-us.apache.org/repos/asf/zeppelin/diff/ff2465b9
Branch: refs/heads/master
Commit: ff2465b9dac8f1fd532f68c0993894a5b0af6595
Parents: 49b3df6
Author: AhyoungRyu <fb...@hanmail.net>
Authored: Sat Aug 13 15:06:13 2016 +0900
Committer: Felix Cheung <fe...@apache.org>
Committed: Thu Aug 18 23:42:07 2016 -0700
----------------------------------------------------------------------
README.md | 2 +-
docs/CONTRIBUTING.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++
docs/README.md | 46 +++++++++++++++--------
pom.xml | 1 +
4 files changed, 126 insertions(+), 17 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/zeppelin/blob/ff2465b9/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 18dba8f..dc3460c 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-#Zeppelin
+# Apache Zeppelin
**Documentation:** [User Guide](http://zeppelin.apache.org/docs/latest/index.html)<br/>
**Mailing Lists:** [User and Dev mailing list](http://zeppelin.apache.org/community.html)<br/>
http://git-wip-us.apache.org/repos/asf/zeppelin/blob/ff2465b9/docs/CONTRIBUTING.md
----------------------------------------------------------------------
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 0000000..7cdb8ad
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,94 @@
+# Contributing to Apache Zeppelin Documentation
+
+## Folder Structure
+`docs/` folder is organized as below:
+
+```
+docs/
+ \u251c\u2500\u2500 _includes/themes/zeppelin
+ \u2502 \u251c\u2500\u2500 _navigation.html
+ \u2502 \u2514\u2500\u2500 default.html
+ \u251c\u2500\u2500 _layouts
+ \u251c\u2500\u2500 _plugins
+ \u251c\u2500\u2500 assets/themes/zeppelin -> {ASSET_PATH}
+ \u2502 \u251c\u2500\u2500 bootstrap
+ \u2502 \u251c\u2500\u2500 css
+ \u2502 \u251c\u2500\u2500 img
+ \u2502 \u2514\u2500\u2500 js
+ \u251c\u2500\u2500 development/ *.md
+ \u251c\u2500\u2500 displaysystem/ *.md
+ \u251c\u2500\u2500 install/ *.md
+ \u251c\u2500\u2500 interpreter/ *.md
+ \u251c\u2500\u2500 manual/ *.md
+ \u251c\u2500\u2500 quickstart/ *.md
+ \u251c\u2500\u2500 rest-api/ *.md
+ \u251c\u2500\u2500 security/ *.md
+ \u251c\u2500\u2500 storage/ *.md
+ \u251c\u2500\u2500 Gemfile
+ \u251c\u2500\u2500 Gemfile.lock
+ \u251c\u2500\u2500 _config.yml
+ \u251c\u2500\u2500 index.md
+ \u2514\u2500\u2500 ...
+```
+
+ - `_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**.
http://git-wip-us.apache.org/repos/asf/zeppelin/blob/ff2465b9/docs/README.md
----------------------------------------------------------------------
diff --git a/docs/README.md b/docs/README.md
index 6e5e716..fdf27fa 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,41 +1,55 @@
-## Apache Zeppelin documentation
-
-This readme will walk you through building the Zeppelin documentation, which is included here with the Zeppelin source code.
+# Apache Zeppelin documentation
+This README will walk you through building the documentation of Apache Zeppelin. The documentation is included here with Apache Zeppelin source code. The online documentation at [https://zeppelin.apache.org/docs/<ZEPPELIN_VERSION>](https://zeppelin.apache.org/docs/latest) is also generated from the files found in here.
## Build documentation
-See https://help.github.com/articles/using-jekyll-with-pages#installing-jekyll
+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
- gem install bundler
- # go to /docs under your Zeppelin source
- bundle install
+# 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).
+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
+```
-*On OS X 10.9 you may need to do "xcode-select --install"*
+## Run website locally
+If you don't want to encounter uglily rendered pages, run the documentation site in your local first.
+In `$ZEPPELIN_HOME/docs`,
-## Run website
+```
+bundle exec jekyll serve --watch
+```
- 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.
-## Adding a new page
- rake page name="new-page.md"
+## Contribute to Zeppelin documentation
+If you wish to help us and contribute to Zeppelin Documentation, please look at [Zeppelin Documentation's contribution guideline](https://github.com/apache/zeppelin/blob/master/docs/CONTRIBUTING.md).
-## Bumping up version in a new release
+## For committers only
+### Bumping up version in a new release
* `ZEPPELIN_VERSION` and `BASE_PATH` property in _config.yml
-## Deploy to ASF svnpubsub infra (for committers only)
+### Deploy to ASF svnpubsub infra
1. generate static website in `./_site`
+
```
# go to /docs under Zeppelin source
bundle exec jekyll build --safe
http://git-wip-us.apache.org/repos/asf/zeppelin/blob/ff2465b9/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index 3e3523e..cd08740 100644
--- a/pom.xml
+++ b/pom.xml
@@ -486,6 +486,7 @@
<exclude>docs/sitemap.txt</exclude>
<exclude>docs/search_data.json</exclude>
<exclude>**/dependency-reduced-pom.xml</exclude>
+ <exclude>docs/CONTRIBUTING.md</exclude>
<!-- bundled from anchor -->
<exclude>docs/assets/themes/zeppelin/js/anchor.min.js</exclude>