[ZEPPELIN-1554] Update jekyll version to 3.2.1 with its dependencies and fix document…

[yoonjs2]

What is this PR for?

• Update outdated jekyll version of zeppelin documentation from 1.x to 3.x
• Eliminate kramdown only warnings when serving documentation as github pages.
• Prepare base environment for L10N related plugins for jekyll.

What type of PR is it?

Improvement | Documentation

Todos

• [*] - Update Jekyll version to 3.x
• [*] - Update documentation style as kramdown

What is the Jira issue?

ZEPPELIN-1554

Questions:

• Does the licenses files need update? No
• Is there breaking changes for older versions? Yes for documentation
• Does this needs documentation? No

… style as kramdown.

[yoonjs2]

@AhyoungRyu Can I ask you to allow me to change JIRA ZEPPELIN-1554 assignee and progress? In case of self proposal and PR like this, It would be great to use JIRA as contributor access :)

[AhyoungRyu]

@yoonjs2 Sure. And let me test this patch :)
@minahlee Could you help me add @yoonjs2 (Jira username:Jesang Yoon) to the contributor list in Jira so that he can assign himself to assignee?

[minahlee]

@yoonjs2 just added your name to contributor role

[yoonjs2]

@AhyoungRyu @minahlee Thanks! Let me know if patch needs any change :)

[AhyoungRyu]

@yoonjs2 Seems "Prepare L10N support on documentation" is unchecked in the PR description. Is it done now?

[yoonjs2]

@AhyoungRyu no, its under progress now. Should I change unchecked todo to other PR?

[AhyoungRyu]

@yoonjs2 yes i think it would be better to handle " L10N support" in other PR since it's a bit different work with this. What do you think?

[yoonjs2]

@AhyoungRyu Fair enough, I'd just removed a todo (L10N support) and It will be proposed different PR.

[AhyoungRyu]

@yoonjs2 Yeah thanks for your consideration!

I've tested this branch and found some issues.

1.

Liquid Warning: Liquid syntax error (line 77): Expected end_of_string but found open_round in "{{noteName(note)}}" in manual/notebookashomepage.md

seems it needs some markdown escaping. The line number 83 in docs/manual/notebookashomepage.md

<a style="text-decoration: none;" href="#/notebook/{{note.id}}">{{noteName(note)}}</a>

it can be fixed simply like below

<a style="text-decoration: none;" href="#/notebook/{{"{{note.id"}}}}>{{"{{noteName(note)"}}}}</a>

then the error message will be gone :)

2. As you know, the docs site will be deployed under zeppelin.apache.org/docs/0.7.0-SNAPSHOT/ not zeppelin.apache.org. So I tested in similar env like below

1) build gh-pages (website) branch
JEKYLL_ENV=production bundle exec jekyll build
cp -r _site/ /tmp/zeppelin_website/
mkdir -p /tmp/zeppelin_website/docs/0.7.0-SNAPSHOT

2) build this patch (docs) and copy it under docs/0.7.0-SNAPSHOT of website
cd docs
bundle exec jekyll build --safe
cp -r _site/ /tmp/zeppelin_website/0.7.0-SNAPSHOT/

3) start httpserver and browse http://localhost:8000/docs/0.7.0-SNAPSHOT/
cd /tmp/zeppelin_website
python -m SimpleHTTPServer

then it throws

and not happened in master. And also some styles are not missing now.

Could you check them again? Please feel free to ping me if you're in trouble while testing.

[yoonjs2]

@AhyoungRyu OK I'll investigate and resolve them ASAP. Thanks for the review :)

[yoonjs2]

@AhyoungRyu I've stucked with the first step you've mentioned...
How do I workaround this error?

1. build gh-pages (website) branch

$ git checkout gh-pages
$ JEKYLL_ENV=production 
$ bundle exec jekyll build

Configuration file: /Users/yoonjesang/Desktop/openfrontier/zeppelin/_config.yml
            Source: /Users/yoonjesang/Desktop/openfrontier/zeppelin
       Destination: /Users/yoonjesang/Desktop/openfrontier/zeppelin/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
  Liquid Exception: Could not locate the included file 'nav/announcements-4.0.html' in any of ["/Users/yoonjesang/Desktop/openfrontier/zeppelin/_includes"]. Ensure it exists in one of those directories and, if it is a symlink, does not point outside your site source. in zeppelin-web/bower_components/select2/docs/announcements-4.0.html
jekyll 3.2.1 | Error:  Could not locate the included file 'nav/announcements-4.0.html' in any of ["/Users/yoonjesang/Desktop/openfrontier/zeppelin/_includes"]. Ensure it exists in one of those directories and, if it is a symlink, does not point outside your site source.

And I found few lines of your instruction seems mistyped... Am I correct?

mkdir -p /tmp/zeppelin-website/docs/0.7.0-SNAPSHOT => mkdir -p /tmp/zeppelin_website/docs/0.7.0-SNAPSHOT

cp -r _site/ /tmp/zeppelin_website/0.7.0-SNAPSHOT/ => cp -r _site/ /tmp/zeppelin_website/docs/0.7.0-SNAPSHOT/

[AhyoungRyu]

@yoonjs2 Yeah you're right, there is a typo. It should be one of them either zeppelin-website or zeppelin_website. I updated the comment :)

And you did like below as you said

$ JEKYLL_ENV=production 
$ bundle exec jekyll build

But it should be in one line

$ JEKYLL_ENV=production bundle exec jekyll build

[1ambda]

Any updated?