[ZEPPELIN-998] Extend install.md -> Quick Start #1010

AhyoungRyu · 2016-06-14T03:29:48Z

What is this PR for?

Most of other projects have Quick Start or Getting Started page for the beginner. Currently, Zeppelin also has Zeppelin Install which is similar with those kind of instruction page. But it has only contents that explain just installation and configuration. So I updated this page to Quick Start so that it can include step by step guide for the beginners.

What type of PR is it?

Improvement & Documentation

Todos

- Add each title link to the head of documentation
- Add more information about Zeppelin installation
- Reorder contents

What is the Jira issue?

ZEPPELIN-998

How should this be tested?

See the attached screenshot images

Screenshots (if appropriate)

### Questions: - Does the licenses files need update? No - Is there breaking changes for older versions? No - Does this needs documentation? No

bzz · 2016-06-14T08:54:32Z

docs/install/install.md

+```
+
+## What is the next?
+Congratulation to your successful Zeppelin installation! Here are two next steps you might need.


I belive it is a typo - it should be Congratulation _on_ as it's not an Apache Zeppelin installation that is being congratulated here, but the user.

@bzz Yeah you're right. I just updated it :)

bzz · 2016-06-14T08:57:11Z

@AhyoungRyu thank you for great effort structuring the docs!

It looks awesome, just two things that I have noticed:

can you please double check that project is referred as Apache Zeppelin everywhere (following branding guidelines)
having npm installed is not a requirement to build project from sources

mvn package should be enough and will take care of installing both, local node as well as NPM so I would suggest we remove mention of npm from 'building from source section'

AhyoungRyu · 2016-06-14T17:04:58Z

@bzz Really appreciated to your review again :)

I added Apache before the most of Zeppelin.
I didn't noticed that "npm, downloaded by Maven during build phase" in README.md#requirements. So I removed it as you said.

bzz · 2016-06-15T07:01:21Z

@AhyoungRyu great job! Let me take another pass on it plz.

Meanwhile, is removal of conf/shiro.ini a part of this quickstart?

bzz · 2016-06-15T07:02:31Z

docs/install/install.md

-Welcome to your first trial to explore Zeppelin!
+# Quick Start
+Welcome to your first trial to explore Apache Zeppelin! 
+This page will help you to get started with Apache Zeppelin. Here is the list of this page. 


This page will help you to get started and here is the list of topics covered

AhyoungRyu · 2016-06-15T07:02:52Z

@bzz Oh my. That's my bad. I'll revert it now :)

bzz · 2016-06-15T07:03:41Z

docs/install/install.md

+## Installation

-If you want to install Zeppelin with latest binary package, please visit [this page](http://zeppelin.apache.org/download.html).
+Apache Zeppelin officially tested on the below environment. 


Apache Zeppelin officially supports and is tested on next environments

bzz · 2016-06-15T07:06:01Z

docs/install/install.md

+After unpacking, jump to [Starting Apache Zeppelin with Command Line](#starting-apache-zeppelin-with-command-line) section.
+
+### Building from Source
+If you want to build from the source, there are more requirements. 


If you want to build from the source, the software below needs to be installed on your system

bzz · 2016-06-15T07:10:46Z

Thanks for prompt response!
Your documentation update looks great to me, modulo few minor suggestions above.

Please feel free to use them at your will, otherwise I think it's ready to be merged.

AhyoungRyu · 2016-06-15T07:14:56Z

@bzz Thanks for all of your suggestions again. I've just addressed them. Please check my last commit :)

bzz · 2016-06-17T01:36:49Z

Looks great to me, thank you @AhyoungRyu

Will merge to master, if there is no further discussion

@bzz

### What is this PR for? Most of other projects have **Quick Start** or **Getting Started** page for the beginner. Currently, Zeppelin also has [Zeppelin Install](https://zeppelin.apache.org/docs/0.6.0-SNAPSHOT/install/install.html) which is similar with those kind of instruction page. But it has only contents that explain just installation and configuration. So I updated this page to **Quick Start** so that it can include step by step guide for the beginners. ### What type of PR is it? Improvement & Documentation ### Todos * [x] - Add each title link to the head of documentation * [x] - Add more information about Zeppelin installation * [x] - Reorder contents ### What is the Jira issue? [ZEPPELIN-998](https://issues.apache.org/jira/browse/ZEPPELIN-998) ### How should this be tested? See the attached screenshot images ### Screenshots (if appropriate) <img width="809" alt="screen shot 2016-06-14 at 2 59 47 pm" src="https://cloud.githubusercontent.com/assets/10060731/16061227/d88abe56-3240-11e6-845c-e37a9975aceb.png"> <img width="796" alt="screen shot 2016-06-14 at 3 00 01 pm" src="https://cloud.githubusercontent.com/assets/10060731/16061229/daca8b06-3240-11e6-821b-7d118b7b3e09.png"> <img width="789" alt="screen shot 2016-06-14 at 3 00 15 pm" src="https://cloud.githubusercontent.com/assets/10060731/16061234/dd12072c-3240-11e6-9a0a-cf1e320fd879.png"> <img width="785" alt="screen shot 2016-06-14 at 3 00 27 pm" src="https://cloud.githubusercontent.com/assets/10060731/16061238/df7f904c-3240-11e6-83e0-73f3688c0815.png"> <img width="789" alt="screen shot 2016-06-14 at 3 00 38 pm" src="https://cloud.githubusercontent.com/assets/10060731/16061242/e1ad1402-3240-11e6-81ba-2e7125cec98e.png"> ### Questions: * Does the licenses files need update? No * Is there breaking changes for older versions? No * Does this needs documentation? No Author: AhyoungRyu <[email protected]> Closes #1010 from AhyoungRyu/ZEPPELIN-998 and squashes the following commits: b2b1aa8 [AhyoungRyu] Change some sentences as @bzz suggested 12da298 [AhyoungRyu] Fix pointing link in index.md af50576 [AhyoungRyu] Address @bzz feedback af68a32 [AhyoungRyu] Extend install.md -> Quick Start (cherry picked from commit 70d22d3) Signed-off-by: Mina Lee <[email protected]>

@felixcheung

…docs website ### What is this PR for? I added auto TOC(Table of Contents) generator for Zeppelin documentation website. TOC can help people looking through whole contents at a glance and finding what they want quickly. I just added `<div id="toc"></div>` to the each documentation header. [`toc`](https://github.com/apache/zeppelin/compare/master...AhyoungRyu:ZEPPELIN-1018?expand=1#diff-85af09fb498a5667ea455391533f945dR3) recognize `<h2>` & `<h3>` as a title in the docs and it automatically generate TOC. So I set a rule for this work. (I'll write this rule on `docs/CONTRIBUTING.md` or [docs/howtocontributewebsite](https://zeppelin.apache.org/docs/0.6.0-SNAPSHOT/development/howtocontributewebsite.html)). ``` # Level-1 Heading <- Use only for the main title of the page ## Level-2 Heading <- Start with this one ### Level-3 heading <- Only use this one for child of Level-2 toc only recognize Level-2 & Level-3 ``` Please see the below attached screenshot image. ### What type of PR is it? Improvement & Documentation ### Todos * [x] - Add TOC generator * [x] - Apply TOC(`<div id="toc"></div>`) to every documentation and reorganize each headers(apply the above rule) * [x] - Fix some broken code block in several docs * [x] - Apply TOC to `r.md` (Currently R docs has some duplicated info since [this one](d5e87fb) and [this one](7d6cc7e) ) * [x] - Apply TOC to `install.md` after #1010 merged * [x] - Apply TOC to `interpreterinstallation.md` after #1042 merged ### What is the Jira issue? [ZEPPELIN-1018](https://issues.apache.org/jira/browse/ZEPPELIN-1018) ### How should this be tested? 1. Apply this patch and build `docs/` with [this guide](https://github.com/apache/zeppelin/tree/master/docs#build-documentation) 2. Visit some docs page. Then you can see TOC in the header of page. ### Screenshots (if appropriate) - Automatically generated TOC in Spark interpreter docs page <img width="831" alt="screen shot 2016-06-16 at 9 37 18 pm" src="https://cloud.githubusercontent.com/assets/10060731/16140902/945b9c7a-340a-11e6-91f3-b6174738bed0.png"> ### Questions: * Does the licenses files need update? No. Actually I used [jekyll-table-of-contents#copyright](https://github.com/ghiculescu/jekyll-table-of-contents#copyright). But I don't need to add a license for this :) * Is there breaking changes for older versions? No * Does this needs documentation? Maybe Author: AhyoungRyu <[email protected]> Closes #1031 from AhyoungRyu/ZEPPELIN-1018 and squashes the following commits: e66397b [AhyoungRyu] Apply TOC to interpreterinstallation.md 009579b [AhyoungRyu] Add more info to 'What is the next?' in install.md 04cf501 [AhyoungRyu] Revert 'where to start' section b7cbe5f [AhyoungRyu] Fix typo cf0911c [AhyoungRyu] Rename license file 388f35a [AhyoungRyu] Add jekyll-table-of-contents license info 6394c70 [AhyoungRyu] Fix image path in python.md d00e4b1 [AhyoungRyu] Move interpreter/screenshot/ -> asset/../img/docs-img/ 3ffb383 [AhyoungRyu] Remove duplicated info in r.md & apply toc a03ca99 [AhyoungRyu] Exclude toc.js from pom.xml 3fae7df [AhyoungRyu] Apply auto generated toc to install.md d114a9d [AhyoungRyu] Address @felixcheung feedback 6a788fe [AhyoungRyu] Resize TOC tab indent 6760c00 [AhyoungRyu] Apply auto TOC to all of docs under docs/storage/ fbde57f [AhyoungRyu] Apply auto TOC to all of docs under docs/quickstart/ db76eb6 [AhyoungRyu] Apply auto TOC to all of docs under docs/install/ f35db47 [AhyoungRyu] Apply auto TOC to all of docs under docs/displaysystem/ b05365f [AhyoungRyu] Apply auto TOC to all of docs under docs/rest-api/ 163691c [AhyoungRyu] Apply auto TOC to all of docs under docs/manual/ bef398e [AhyoungRyu] Apply auto TOC to all of docs under docs/development/ 9c5f76b [AhyoungRyu] Apply auto TOC to all of docs under docs/interpreter/ 587d4ba [AhyoungRyu] Apply auto TOC to all of docs under docs/security/ 1f10b97 [AhyoungRyu] Change toc configuration 78dca9e [AhyoungRyu] Add toc.js for auto generating TOC

@felixcheung

…docs website ### What is this PR for? I added auto TOC(Table of Contents) generator for Zeppelin documentation website. TOC can help people looking through whole contents at a glance and finding what they want quickly. I just added `<div id="toc"></div>` to the each documentation header. [`toc`](https://github.com/apache/zeppelin/compare/master...AhyoungRyu:ZEPPELIN-1018?expand=1#diff-85af09fb498a5667ea455391533f945dR3) recognize `<h2>` & `<h3>` as a title in the docs and it automatically generate TOC. So I set a rule for this work. (I'll write this rule on `docs/CONTRIBUTING.md` or [docs/howtocontributewebsite](https://zeppelin.apache.org/docs/0.6.0-SNAPSHOT/development/howtocontributewebsite.html)). ``` # Level-1 Heading <- Use only for the main title of the page ## Level-2 Heading <- Start with this one ### Level-3 heading <- Only use this one for child of Level-2 toc only recognize Level-2 & Level-3 ``` Please see the below attached screenshot image. ### What type of PR is it? Improvement & Documentation ### Todos * [x] - Add TOC generator * [x] - Apply TOC(`<div id="toc"></div>`) to every documentation and reorganize each headers(apply the above rule) * [x] - Fix some broken code block in several docs * [x] - Apply TOC to `r.md` (Currently R docs has some duplicated info since [this one](d5e87fb) and [this one](7d6cc7e) ) * [x] - Apply TOC to `install.md` after #1010 merged * [x] - Apply TOC to `interpreterinstallation.md` after #1042 merged ### What is the Jira issue? [ZEPPELIN-1018](https://issues.apache.org/jira/browse/ZEPPELIN-1018) ### How should this be tested? 1. Apply this patch and build `docs/` with [this guide](https://github.com/apache/zeppelin/tree/master/docs#build-documentation) 2. Visit some docs page. Then you can see TOC in the header of page. ### Screenshots (if appropriate) - Automatically generated TOC in Spark interpreter docs page <img width="831" alt="screen shot 2016-06-16 at 9 37 18 pm" src="https://cloud.githubusercontent.com/assets/10060731/16140902/945b9c7a-340a-11e6-91f3-b6174738bed0.png"> ### Questions: * Does the licenses files need update? No. Actually I used [jekyll-table-of-contents#copyright](https://github.com/ghiculescu/jekyll-table-of-contents#copyright). But I don't need to add a license for this :) * Is there breaking changes for older versions? No * Does this needs documentation? Maybe Author: AhyoungRyu <[email protected]> Closes #1031 from AhyoungRyu/ZEPPELIN-1018 and squashes the following commits: e66397b [AhyoungRyu] Apply TOC to interpreterinstallation.md 009579b [AhyoungRyu] Add more info to 'What is the next?' in install.md 04cf501 [AhyoungRyu] Revert 'where to start' section b7cbe5f [AhyoungRyu] Fix typo cf0911c [AhyoungRyu] Rename license file 388f35a [AhyoungRyu] Add jekyll-table-of-contents license info 6394c70 [AhyoungRyu] Fix image path in python.md d00e4b1 [AhyoungRyu] Move interpreter/screenshot/ -> asset/../img/docs-img/ 3ffb383 [AhyoungRyu] Remove duplicated info in r.md & apply toc a03ca99 [AhyoungRyu] Exclude toc.js from pom.xml 3fae7df [AhyoungRyu] Apply auto generated toc to install.md d114a9d [AhyoungRyu] Address @felixcheung feedback 6a788fe [AhyoungRyu] Resize TOC tab indent 6760c00 [AhyoungRyu] Apply auto TOC to all of docs under docs/storage/ fbde57f [AhyoungRyu] Apply auto TOC to all of docs under docs/quickstart/ db76eb6 [AhyoungRyu] Apply auto TOC to all of docs under docs/install/ f35db47 [AhyoungRyu] Apply auto TOC to all of docs under docs/displaysystem/ b05365f [AhyoungRyu] Apply auto TOC to all of docs under docs/rest-api/ 163691c [AhyoungRyu] Apply auto TOC to all of docs under docs/manual/ bef398e [AhyoungRyu] Apply auto TOC to all of docs under docs/development/ 9c5f76b [AhyoungRyu] Apply auto TOC to all of docs under docs/interpreter/ 587d4ba [AhyoungRyu] Apply auto TOC to all of docs under docs/security/ 1f10b97 [AhyoungRyu] Change toc configuration 78dca9e [AhyoungRyu] Add toc.js for auto generating TOC (cherry picked from commit 5975125) Signed-off-by: Mina Lee <[email protected]>

bzz reviewed Jun 14, 2016
View reviewed changes

AhyoungRyu force-pushed the ZEPPELIN-998 branch from 1e39498 to cf103a0 Compare June 14, 2016 17:00

AhyoungRyu force-pushed the ZEPPELIN-998 branch from cf103a0 to c58ad98 Compare June 15, 2016 07:00

bzz reviewed Jun 15, 2016
View reviewed changes

AhyoungRyu added 3 commits June 15, 2016 00:05

Extend install.md -> Quick Start

af68a32

Address @bzz feedback

af50576

Fix pointing link in index.md

12da298

AhyoungRyu force-pushed the ZEPPELIN-998 branch from c58ad98 to 12da298 Compare June 15, 2016 07:06

bzz reviewed Jun 15, 2016
View reviewed changes

Change some sentences as @bzz suggested

b2b1aa8

AhyoungRyu force-pushed the ZEPPELIN-998 branch from b2b1aa8 to 207491f Compare June 15, 2016 17:20

AhyoungRyu closed this Jun 15, 2016

AhyoungRyu reopened this Jun 15, 2016

AhyoungRyu force-pushed the ZEPPELIN-998 branch 3 times, most recently from 5aa330c to b2b1aa8 Compare June 15, 2016 20:46

AhyoungRyu changed the title ~~[ZEPPELIN-998] Extend install.md -> Quick Start~~ [ZEPPELIN-998][WIP] Extend install.md -> Quick Start Jun 16, 2016

AhyoungRyu changed the title ~~[ZEPPELIN-998][WIP] Extend install.md -> Quick Start~~ [ZEPPELIN-998] Extend install.md -> Quick Start Jun 17, 2016

AhyoungRyu mentioned this pull request Jun 17, 2016

[ZEPPELIN-1018] Apply auto "Table of Contents" generator to Zeppelin docs website #1031

Closed

6 tasks

asfgit closed this in 70d22d3 Jun 20, 2016

[ZEPPELIN-998] Extend install.md -> Quick Start #1010

[ZEPPELIN-998] Extend install.md -> Quick Start #1010

Uh oh!

Conversation

AhyoungRyu commented Jun 14, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is this PR for?

What type of PR is it?

Todos

What is the Jira issue?

How should this be tested?

Screenshots (if appropriate)

Uh oh!

bzz Jun 14, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AhyoungRyu Jun 14, 2016

Choose a reason for hiding this comment

Uh oh!

bzz commented Jun 14, 2016

Uh oh!

AhyoungRyu commented Jun 14, 2016

Uh oh!

bzz commented Jun 15, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bzz Jun 15, 2016

Choose a reason for hiding this comment

Uh oh!

AhyoungRyu commented Jun 15, 2016

Uh oh!

bzz Jun 15, 2016

Choose a reason for hiding this comment

Uh oh!

bzz Jun 15, 2016

Choose a reason for hiding this comment

Uh oh!

bzz commented Jun 15, 2016

Uh oh!

AhyoungRyu commented Jun 15, 2016

Uh oh!

bzz commented Jun 17, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AhyoungRyu commented Jun 14, 2016 •

edited

Loading

bzz Jun 14, 2016 •

edited

Loading

bzz commented Jun 15, 2016 •

edited

Loading