[ZEPPELIN-1018] Apply auto "Table of Contents" generator to Zeppelin docs website by AhyoungRyu · Pull Request #1031 · apache/zeppelin

AhyoungRyu · 2016-06-17T05:29:46Z

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 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).

# 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

- Add TOC generator
- Apply TOC(<div id="toc"></div>) to every documentation and reorganize each headers(apply the above rule)
- Fix some broken code block in several docs
- Apply TOC to r.md (Currently R docs has some duplicated info since this one and this one )
- Apply TOC to install.md after [ZEPPELIN-998] Extend install.md -> Quick Start #1010 merged
- Apply TOC to interpreterinstallation.md after [ZEPPELIN-1046] bin/install-interpreter.sh for netinst package #1042 merged

What is the Jira issue?

ZEPPELIN-1018

How should this be tested?

Apply this patch and build docs/ with this guide
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

Questions:

Does the licenses files need update?
No. Actually I used 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

felixcheung · 2016-06-17T07:06:11Z

docs/development/howtocontributewebsite.md

+
+### git access

+First of all, you need the website source code. The official location of mirror for Zeppelin is [http://git.apache.org/zeppelin.git](http://git.apache.org/zeppelin.git).


I think git.apache.org is the actual source code, not a "mirror", but we are told not to have github.com address here.

@felixcheung I'm not sure I understood correctly, as you can see in git.apache.org at the first sentence, they said

This is a collection of read-only Git mirrors of Apache codebases.

Am I missing sth ?

AhyoungRyu · 2016-06-17T08:07:31Z

@felixcheung Really appreciate your feedback. I just addressed them :)

AhyoungRyu · 2016-06-21T16:43:19Z

TODO list is done for now. This PR has big changes in overall documentation, but most of them is for reorganization the title & header in each docs for more well-organized TOC.
So ready for review :)

Leemoonsoo · 2016-06-23T05:05:25Z

docs/assets/themes/zeppelin/js/toc.js

@@ -0,0 +1,98 @@
+// https://github.com/ghiculescu/jekyll-table-of-contents


Could you add license entry of toc.js into LICENSE file and make a copy of license under licenses directory, while this file will be included in our source distribution?

@Leemoonsoo Yeah I added the license info as you said.

minahlee · 2016-06-24T02:15:13Z

It looks great to me. Thanks for improving document

AhyoungRyu · 2016-06-24T02:26:22Z

@minahlee My pleasure, thanks :)

@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 <fbdkdud93@hanmail.net> 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 <minalee@apache.org>

### What is this PR for? After #836 and #1031 merged into master branch, I also applied TOC(table of contents) to newly added `writingzeppelinapplication.md`. And also added this docs link under `index.md`'s docs list. ### What type of PR is it? Documentation ### Todos * [x] - Apply TOC(table of contents) to `writingzeppelinapplication.md` and add this docs to `index.md` ### Questions: * Does the licenses files need update? no * Is there breaking changes for older versions? no * Does this needs documentation? no Author: AhyoungRyu <fbdkdud93@hanmail.net> Closes #1133 from AhyoungRyu/docs/ZEPPELIN-732 and squashes the following commits: 9fc746f [AhyoungRyu] Fix a grammar error e144e0d [AhyoungRyu] Apply toc to writingzeppelinapplication.md 7dc0b95 [AhyoungRyu] Add writingzeppelinapplication.md to index.md

### What is this PR for? After apache#836 and apache#1031 merged into master branch, I also applied TOC(table of contents) to newly added `writingzeppelinapplication.md`. And also added this docs link under `index.md`'s docs list. ### What type of PR is it? Documentation ### Todos * [x] - Apply TOC(table of contents) to `writingzeppelinapplication.md` and add this docs to `index.md` ### Questions: * Does the licenses files need update? no * Is there breaking changes for older versions? no * Does this needs documentation? no Author: AhyoungRyu <fbdkdud93@hanmail.net> Closes apache#1133 from AhyoungRyu/docs/ZEPPELIN-732 and squashes the following commits: 9fc746f [AhyoungRyu] Fix a grammar error e144e0d [AhyoungRyu] Apply toc to writingzeppelinapplication.md 7dc0b95 [AhyoungRyu] Add writingzeppelinapplication.md to index.md

### 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 <fbdkdud93@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

AhyoungRyu force-pushed the ZEPPELIN-1018 branch from 0315d5c to 4e90a5f Compare June 17, 2016 05:57

felixcheung reviewed Jun 17, 2016
View reviewed changes

AhyoungRyu force-pushed the ZEPPELIN-1018 branch from 1c4c330 to ecbd6a2 Compare June 17, 2016 08:05

AhyoungRyu force-pushed the ZEPPELIN-1018 branch 3 times, most recently from 2947a40 to 0220516 Compare June 21, 2016 05:02

AhyoungRyu closed this Jun 21, 2016

AhyoungRyu reopened this Jun 21, 2016

AhyoungRyu force-pushed the ZEPPELIN-1018 branch from 8433b9a to a5c1e9d Compare June 22, 2016 17:04

Leemoonsoo reviewed Jun 23, 2016
View reviewed changes

AhyoungRyu force-pushed the ZEPPELIN-1018 branch 2 times, most recently from 7c24a84 to a009a6a Compare June 23, 2016 16:59

AhyoungRyu force-pushed the ZEPPELIN-1018 branch 3 times, most recently from c042199 to be79f11 Compare June 25, 2016 19:42

AhyoungRyu added 4 commits June 25, 2016 12:45

Add toc.js for auto generating TOC

78dca9e

Change toc configuration

1f10b97

Apply auto TOC to all of docs under docs/security/

587d4ba

Apply auto TOC to all of docs under docs/interpreter/

9c5f76b

AhyoungRyu added 20 commits June 25, 2016 12:45

Apply auto TOC to all of docs under docs/development/

bef398e

Apply auto TOC to all of docs under docs/manual/

163691c

Apply auto TOC to all of docs under docs/rest-api/

b05365f

Apply auto TOC to all of docs under docs/displaysystem/

f35db47

Apply auto TOC to all of docs under docs/install/

db76eb6

Apply auto TOC to all of docs under docs/quickstart/

fbde57f

Apply auto TOC to all of docs under docs/storage/

6760c00

Resize TOC tab indent

6a788fe

Address @felixcheung feedback

d114a9d

Apply auto generated toc to install.md

3fae7df

Exclude toc.js from pom.xml

a03ca99

Remove duplicated info in r.md & apply toc

3ffb383

Move interpreter/screenshot/ -> asset/../img/docs-img/

d00e4b1

Fix image path in python.md

6394c70

Add jekyll-table-of-contents license info

388f35a

Rename license file

cf0911c

Fix typo

b7cbe5f

Revert 'where to start' section

04cf501

Add more info to 'What is the next?' in install.md

009579b

Apply TOC to interpreterinstallation.md

e66397b

AhyoungRyu force-pushed the ZEPPELIN-1018 branch from 78469af to e66397b Compare June 25, 2016 19:46

asfgit closed this in 5975125 Jun 26, 2016

AhyoungRyu mentioned this pull request Jul 5, 2016

[DOC][ZEPPELIN-732] Helium Application #1133

Closed

1 task

AhyoungRyu mentioned this pull request Aug 12, 2016

[ZEPPELIN-1323] Add contribution guide for Zeppelin documentation #1326

Closed

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

[ZEPPELIN-1018] Apply auto "Table of Contents" generator to Zeppelin docs website#1031
AhyoungRyu wants to merge 24 commits intoapache:masterfrom
AhyoungRyu:ZEPPELIN-1018

AhyoungRyu commented Jun 17, 2016 •

edited

Loading

Uh oh!

felixcheung Jun 17, 2016

Uh oh!

AhyoungRyu Jun 17, 2016 •

edited

Loading

Uh oh!

AhyoungRyu commented Jun 17, 2016 •

edited

Loading

Uh oh!

AhyoungRyu commented Jun 21, 2016

Uh oh!

Leemoonsoo Jun 23, 2016

Uh oh!

AhyoungRyu Jun 23, 2016 •

edited

Loading

Uh oh!

minahlee commented Jun 24, 2016

Uh oh!

AhyoungRyu commented Jun 24, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		### git access

		First of all, you need the website source code. The official location of mirror for Zeppelin is [http://git.apache.org/zeppelin.git](http://git.apache.org/zeppelin.git).

		@@ -0,0 +1,98 @@
		// https://github.com/ghiculescu/jekyll-table-of-contents

Conversation

AhyoungRyu commented Jun 17, 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)

Questions:

Uh oh!

felixcheung Jun 17, 2016

Choose a reason for hiding this comment

Uh oh!

AhyoungRyu Jun 17, 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 commented Jun 17, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AhyoungRyu commented Jun 21, 2016

Uh oh!

Leemoonsoo Jun 23, 2016

Choose a reason for hiding this comment

Uh oh!

AhyoungRyu Jun 23, 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!

minahlee commented Jun 24, 2016

Uh oh!

AhyoungRyu commented Jun 24, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AhyoungRyu commented Jun 17, 2016 •

edited

Loading

AhyoungRyu Jun 17, 2016 •

edited

Loading

AhyoungRyu commented Jun 17, 2016 •

edited

Loading

AhyoungRyu Jun 23, 2016 •

edited

Loading