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 <fbdkdu...@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 <fbdkdu...@hanmail.net> Authored: Sat Aug 13 15:06:13 2016 +0900 Committer: Felix Cheung <felixche...@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/ + âââ _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**. 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>
