[FLINK-5258] [docs] Reorganize the docs to improve navigation and red…

…uce duplication

This closes apache#2940

docs/Gemfile

@@ -17,11 +17,13 @@
 ################################################################################
 
 source 'https://rubygems.org'
-
-ruby '>=1.9.0'
+ruby '~> 2.3.0'
 
 # Dependencies required to build the Flink docs
-gem 'jekyll', '2.5.3'
-gem 'kramdown', '1.10.0'
+gem 'jekyll', '~> 3.3.0'
+gem 'kramdown', '~> 1.13.0'
 gem 'pygments.rb', '0.6.3'
 gem 'therubyracer', '0.12.2'
+group :jekyll_plugins do
+ gem 'hawkins'
+end

docs/Gemfile.lock

@@ -1,88 +1,72 @@
 GEM
  remote: https://rubygems.org/
  specs:
- addressable (2.4.0)
- blankslate (2.1.2.4)
- classifier-reborn (2.0.4)
- fast-stemmer (~> 1.0)
- coffee-script (2.4.1)
- coffee-script-source
- execjs
- coffee-script-source (1.11.1)
- colorator (0.1)
- execjs (2.7.0)
- faraday (0.9.2)
- multipart-post (>= 1.2, < 3)
- fast-stemmer (1.0.2)
+ addressable (2.5.0)
+ public_suffix (~> 2.0, >= 2.0.2)
+ colorator (1.1.0)
+ em-websocket (0.5.1)
+ eventmachine (>= 0.12.9)
+ http_parser.rb (~> 0.6.0)
+ eventmachine (1.2.1)
  ffi (1.9.14)
- jekyll (2.5.3)
- classifier-reborn (~> 2.0)
- colorator (~> 0.1)
- jekyll-coffeescript (~> 1.0)
- jekyll-gist (~> 1.0)
- jekyll-paginate (~> 1.0)
+ forwardable-extended (2.6.0)
+ hawkins (2.0.4)
+ em-websocket (~> 0.5)
+ jekyll (~> 3.1)
+ http_parser.rb (0.6.0)
+ jekyll (3.3.1)
+ addressable (~> 2.4)
+ colorator (~> 1.0)
  jekyll-sass-converter (~> 1.0)
  jekyll-watch (~> 1.1)
  kramdown (~> 1.3)
- liquid (~> 2.6.1)
+ liquid (~> 3.0)
  mercenary (~> 0.3.3)
- pygments.rb (~> 0.6.0)
- redcarpet (~> 3.1)
+ pathutil (~> 0.9)
+ rouge (~> 1.7)
  safe_yaml (~> 1.0)
- toml (~> 0.1.0)
- jekyll-coffeescript (1.0.1)
- coffee-script (~> 2.2)
- jekyll-gist (1.4.0)
- octokit (~> 4.3.0)
- jekyll-paginate (1.1.0)
  jekyll-sass-converter (1.5.0)
  sass (~> 3.4)
  jekyll-watch (1.5.0)
  listen (~> 3.0, < 3.1)
- kramdown (1.10.0)
+ kramdown (1.13.1)
  libv8 (3.16.14.17)
- liquid (2.6.3)
+ liquid (3.0.6)
  listen (3.0.8)
  rb-fsevent (~> 0.9, >= 0.9.4)
  rb-inotify (~> 0.9, >= 0.9.7)
  mercenary (0.3.6)
- multipart-post (2.0.0)
- octokit (4.3.0)
- sawyer (~> 0.7.0, >= 0.5.3)
- parslet (1.5.0)
- blankslate (~> 2.0)
+ pathutil (0.14.0)
+ forwardable-extended (~> 2.6)
  posix-spawn (0.3.12)
+ public_suffix (2.0.4)
  pygments.rb (0.6.3)
  posix-spawn (~> 0.3.6)
  yajl-ruby (~> 1.2.0)
  rb-fsevent (0.9.8)
  rb-inotify (0.9.7)
  ffi (>= 0.5.0)
- redcarpet (3.3.4)
  ref (2.0.0)
+ rouge (1.11.1)
  safe_yaml (1.0.4)
  sass (3.4.22)
- sawyer (0.7.0)
- addressable (>= 2.3.5, < 2.5)
- faraday (~> 0.8, < 0.10)
  therubyracer (0.12.2)
  libv8 (~> 3.16.14.0)
  ref
- toml (0.1.2)
- parslet (~> 1.5.0)
  yajl-ruby (1.2.1)
 
 PLATFORMS
  ruby
 
 DEPENDENCIES
- jekyll (= 2.5.3)
- kramdown (= 1.10.0)
+ hawkins
+ jekyll (~> 3.3.0)
+ kramdown (~> 1.13.0)
  pygments.rb (= 0.6.3)
  therubyracer (= 0.12.2)
 
 RUBY VERSION
  ruby 2.3.1p112
 
 BUNDLED WITH
- 1.13.2
+ 1.13.6

docs/_includes/sidenav.html

@@ -101,6 +101,8 @@
  {% capture target %}"{{ site.baseurl }}{{ this.url }}"{% if active %} class="active"{% endif %}{% endcapture %}
  {% capture overview_target %}"{{ site.baseurl }}{{ this.url }}"{% if this.url == page.url %} class="active"{% endif %}{% endcapture %}
 
+ {% if this.section-break %}<hr class="section-break"></hr>{% endif %}
+
  {% assign pos = pos | plus: 1 %}
  {% if this.nav-id %}
  {% assign children = (site.pages | where: "nav-parent_id" , this.nav-id | sort: "nav-pos") %}
@@ -124,7 +126,7 @@
  {% endif %}
 {% endfor %}
  <li class="divider"></li>
- <li><a href="http://flink.apache.org"><i class="fa fa-external-link" aria-hidden="true"></i> Project Page</a></li>
+ <li><a href="http://flink.apache.org"><i class="fa fa-external-link title" aria-hidden="true"></i> Project Page</a></li>
 </ul>
 
 <div class="sidenav-search-box">

docs/build_docs.sh

@@ -46,11 +46,15 @@ DOCS_DST=${DOCS_SRC}/content
 JEKYLL_CMD="build"
 
 # if -p flag is provided, serve site on localhost
-while getopts ":p" opt; do
+# -i is like -p, but incremental (which has some issues, but is very fast)
+while getopts ":p:i" opt; do
  case $opt in
  p)
  JEKYLL_CMD="serve --baseurl= --watch"
  ;;
+ i)
+ JEKYLL_CMD="liveserve --baseurl= --watch --incremental"
+ ;;
  esac
 done