GitHub user AhyoungRyu opened a pull request:
https://github.com/apache/zeppelin/pull/1031
[ZEPPELIN-1018] Apply auto "Table of Contents" generator to Zeppelin 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
* [ ] - Apply TOC to `r.md` (Currently R docs has some duplicated info
since [this
one](https://github.com/apache/zeppelin/commit/d5e87fb8ba98f08db5b0a4995104ce19f182c678)
and [this
one](https://github.com/apache/zeppelin/commit/7d6cc7e99154e2d337c11fdf8be1a874ed3e9ada)
)
* [ ] - Apply TOC to `install.md` after #1010 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
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/AhyoungRyu/incubator-zeppelin ZEPPELIN-1018
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/zeppelin/pull/1031.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #1031
----
commit 162193a8a57475480898ee84290e83d36462febe
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T01:10:06Z
Add toc.js for auto generating TOC
commit ba57b519c3f12bc61ecbb80b0d0c06158c08c485
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:40:17Z
Change toc configuration
commit 711ab09f8dd6c056dedf3fb4c8bd43633fa3e8d2
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:41:49Z
Apply auto TOC to all of docs under docs/security/
commit c9848c47ba5963db2b1946260f251fe3288675fe
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:42:17Z
Apply auto TOC to all of docs under docs/interpreter/
commit 796530e350b76a5ed36a4a6e516cd2eee0248bcc
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:42:32Z
Apply auto TOC to all of docs under docs/development/
commit 002ec825e7f7edb5f88372e298501c2bffcbdbf6
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:42:46Z
Apply auto TOC to all of docs under docs/manual/
commit a79fef6ec27ffdf5abf623cc1580301b5fed3d02
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:42:59Z
Apply auto TOC to all of docs under docs/rest-api/
commit 41fbdeb1418a4db91b9362586e002608e135844b
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:43:15Z
Apply auto TOC to all of docs under docs/displaysystem/
commit 3f9fd674c1b1b86a04c4d4b03f636a2af1acf651
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:43:28Z
Apply auto TOC to all of docs under docs/install/
commit f62fb1b77fd32b3e850c1aee166f4cfcebba094e
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:43:40Z
Apply auto TOC to all of docs under docs/quickstart/
commit 17ff694d93e4871e69dd667f293b1bf6b38c5e2f
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:44:01Z
Apply auto TOC to all of docs under docs/storage/
commit 0315d5c3901d54ba3ce85401665a6a2f4f42799f
Author: AhyoungRyu <[email protected]>
Date: 2016-06-17T02:44:47Z
Resize TOC tab indent
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
![https://cloud.githubusercontent.com/assets/10060731/16140902/945b9c7a-340a-11e6-91f3-b6174738bed0.png"](https://cloud.githubusercontent.com/assets/10060731/16140902/945b9c7a-340a-11e6-91f3-b6174738bed0.png"){kind=link}