Skip to content

Commit

Permalink
[FLINK-4317, FLIP-3] [docs] Restructure docs
Browse files Browse the repository at this point in the history
- Add redirect layout
- Remove Maven artifact name warning
- Add info box if stable, but not latest
- Add font-awesome 4.6.3
- Add sidenav layout

This closes apache#2387.
  • Loading branch information
uce committed Aug 24, 2016
1 parent c09ff03 commit 844c874
Show file tree
Hide file tree
Showing 225 changed files with 4,748 additions and 1,839 deletions.
5 changes: 3 additions & 2 deletions LICENSE
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ The Apache Flink project bundles the following files under the MIT License:
- dagre v0.7.4 (https://github.com/cpettitt/dagre) - Copyright (c) 2012-2014 Chris Pettitt
- dagre-d3 v0.4.17 (https://github.com/cpettitt/dagre-d3) - Copyright (c) 2013 Chris Pettitt
- EvEmitter v1.0.2 (https://github.com/metafizzy/ev-emitter) - Copyright (C) 2016 David DeSandro
- Font Awesome (code) v4.5.0 (http:https://fontawesome.io) - Copyright (c) 2014 Dave Gandy
- Font Awesome (code) v4.5.0, v4.6.3 (http:https://fontawesome.io) - Copyright (c) 2014 Dave Gandy
- graphlib v1.0.7 (https://github.com/cpettitt/graphlib) - Copyright (c) 2012-2014 Chris Pettitt
- imagesloaded v4.1.0 (https://github.com/desandro/imagesloaded) - Copyright (C) 2016 David DeSandro
- JQuery v2.2.0 (http:https://jquery.com/) - Copyright 2014 jQuery Foundation and other contributors
Expand Down Expand Up @@ -300,7 +300,8 @@ The Apache Flink project bundles the following fonts under the
Open Font License (OFT) - http:https://scripts.sil.org/OFL

- Font Awesome (http:https://fortawesome.github.io/Font-Awesome/) - Created by Dave Gandy
-> fonts in "flink-runtime-web/web-dashboard/assets/fonts"
-> fonts in "flink-runtime-web/web-dashboard/web/fonts"
-> fonts in "docs/page/font-awesome/fonts"

-----------------------------------------------------------------------
The ISC License
Expand Down
42 changes: 9 additions & 33 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,43 +109,19 @@ These will be replaced by a info or warning label. You can change the text of th

### Documentation

#### Top Navigation
#### Navigation

You can modify the top-level navigation in two places. You can either edit the `_includes/navbar.html` file or add tags to your page frontmatter (recommended).
The navigation on the left side of the docs is automatically generated when building the docs. You can modify the markup in `_include/sidenav.html`.

# Top-level navigation
top-nav-group: apis
top-nav-pos: 2
top-nav-title: <strong>Batch Guide</strong> (DataSet API)
The structure of the navigation is determined by the front matter of all pages. The fields used to determine the structure are:

This adds the page to the group `apis` (via `top-nav-group`) at position `2` (via `top-nav-pos`). Furthermore, it specifies a custom title for the navigation via `top-nav-title`. If this field is missing, the regular page title (via `title`) will be used. If no position is specified, the element will be added to the end of the group. If no group is specified, the page will not show up.
- `nav-id` => ID of this page. Other pages can use this ID as their parent ID.
- `nav-parent_id` => ID of the parent. This page will be listed under the page with id `nav-parent_id`.

Currently, there are groups `quickstart`, `setup`, `deployment`, `apis`, `libs`, and `internals`.
Level 0 is made up of all pages, which have nav-parent_id set to `root`. There is no limitation on how many levels you can nest.

#### Sub Navigation
The `title` of the page is used as the default link text. You can override this via `nav-title`. The relative position per navigational level is determined by `nav-pos`.

A sub navigation is shown if the field `sub-nav-group` is specified. A sub navigation groups all pages with the same `sub-nav-group`. Check out the streaming or batch guide as an example.
If you have a page with sub pages, the link target will be used to expand the sub level navigation. If you want to actually add a link to the page as well, you can add the `nav-show_overview: true` field to the front matter. This will then add an `Overview` sub page to the expanded list.

# Sub-level navigation
sub-nav-group: batch
sub-nav-id: dataset_api
sub-nav-pos: 1
sub-nav-title: DataSet API

The fields work similar to their `top-nav-*` counterparts.

In addition, you can specify a hierarchy via `sub-nav-id` and `sub-nav-parent`:

# Sub-level navigation
sub-nav-group: batch
sub-nav-parent: dataset_api
sub-nav-pos: 1
sub-nav-title: Transformations

This will show the `Transformations` page under the `DataSet API` page. The `sub-nav-parent` field has to have a matching `sub-nav-id`.

#### Breadcrumbs

Pages with sub navigations can use breadcrumbs like `Batch Guide > Libraries > Machine Learning > Optimization`.

The breadcrumbs for the last page are generated from the front matter. For the a sub navigation root to appear (like `Batch Guide` in the example above), you have to specify the `sub-nav-group-title`. This field designates a group page as the root.
The nesting is also used for the breadcrumbs like `Application Development > Libraries > Machine Learning > Optimization`.
17 changes: 15 additions & 2 deletions docs/_config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
version: "1.2-SNAPSHOT"
version_hadoop1: "1.2-hadoop1-SNAPSHOT"
version_short: "1.2" # Used for the top navbar w/o snapshot suffix
is_snapshot_version: true

# This suffix is appended to the Scala-dependent Maven artifact names
scala_version_suffix: "_2.10"
Expand All @@ -40,21 +41,33 @@ jira_url: "https://issues.apache.org/jira/browse/FLINK"
github_url: "https://github.com/apache/flink"
download_url: "http:https://flink.apache.org/downloads.html"

# Flag whether this is the latest stable version or not. If not, a warning
# will be printed pointing to the docs of the latest stable version.
is_latest: true
is_stable: false
latest_stable_url: http:https://ci.apache.org/projects/flink/flink-docs-release-1.1

previous_docs:
1.1: http:https://ci.apache.org/projects/flink/flink-docs-release-1.1
1.0: http:https://ci.apache.org/projects/flink/flink-docs-release-1.0

#------------------------------------------------------------------------------
# BUILD CONFIG
#------------------------------------------------------------------------------
# These variables configure the jekyll build (./build_docs.sh). You don't need
# to change anything here.
#------------------------------------------------------------------------------

# Used in some documents to initialize arrays. Don't delete.
array: []

defaults:
-
scope:
path: ""
values:
layout: plain
top-nav-pos: 99999 # Move to end
sub-nav-pos: 99999 # Move to end
nav-pos: 99999 # Move to end if no pos specified

markdown: KramdownPygments
highlighter: pygments
Expand Down
117 changes: 0 additions & 117 deletions docs/_includes/navbar.html

This file was deleted.

149 changes: 149 additions & 0 deletions docs/_includes/sidenav.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http:https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->

{% comment %}
==============================================================================
Extract the active nav IDs.
==============================================================================
{% endcomment %}

{% assign active_nav_ids = site.array %}
{% assign parent_id = page.nav-parent_id %}

{% for i in (1..10) %}
{% if parent_id %}
{% assign active_nav_ids = active_nav_ids | push: parent_id %}
{% assign current = (site.pages | where: "nav-id" , parent_id | sort: "nav-pos") %}
{% if current.size > 0 %}
{% assign parent_id = current[0].nav-parent_id %}
{% else %}
{% break %}
{% endif %}
{% else %}
{% break %}
{% endif %}
{% endfor %}

{% comment %}
==============================================================================
Build the nested list from nav-id and nav-parent_id relations.
==============================================================================
This builds a nested list from all pages. The fields used to determine the
structure are:

- 'nav-id' => ID of this page. Other pages can use this ID as their
parent ID.
- 'nav-parent_id' => ID of the parent. This page will be listed under
the page with id 'nav-parent_id'.

Level 0 is made up of all pages, which have nav-parent_id set to 'root'.

The 'title' of the page is used as the default link text. You can
override this via 'nav-title'. The relative position per navigational
level is determined by 'nav-pos'.
{% endcomment %}

{% assign elementsPosStack = site.array %}
{% assign posStack = site.array %}

{% assign elements = site.array %}
{% assign children = (site.pages | where: "nav-parent_id" , "root" | sort: "nav-pos") %}
{% if children.size > 0 %}
{% assign elements = elements | push: children %}
{% endif %}

{% assign elementsPos = 0 %}
{% assign pos = 0 %}

<div class="sidenav-logo">
<p><a href="{{ site.baseurl }}"><img class="bottom" alt="Apache Flink" src="{{ site.baseurl }}/page/img/navbar-brand-logo.jpg"></a> v{{ site.version }}</p>
</div>
<ul id="sidenav">
{% for i in (1..10000) %}
{% if pos >= elements[elementsPos].size %}
{% if elementsPos == 0 %}
{% break %}
{% else %}
{% assign elementsPos = elementsPosStack | last %}
{% assign pos = posStack | last %}
</li></ul></div>
{% assign elementsPosStack = elementsPosStack | pop %}
{% assign posStack = posStack | pop %}
{% endif %}
{% else %}
{% assign this = elements[elementsPos][pos] %}

{% if this.url == page.url %}
{% assign active = true %}
{% elsif this.nav-id and active_nav_ids contains this.nav-id %}
{% assign active = true %}
{% else %}
{% assign active = false %}
{% endif %}

{% capture title %}{% if this.nav-title %}{{ this.nav-title }}{% else %}{{ this.title }}{% endif %}{% endcapture %}
{% 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 %}

{% assign pos = pos | plus: 1 %}
{% if this.nav-id %}
{% assign children = (site.pages | where: "nav-parent_id" , this.nav-id | sort: "nav-pos") %}
{% if children.size > 0 %}
{% capture collapse_target %}"#collapse-{{ i }}" data-toggle="collapse"{% if active %} class="active"{% endif %}{% endcapture %}
{% capture expand %}{% unless active %} <i class="fa fa-caret-down pull-right" aria-hidden="true" style="padding-top: 4px"></i>{% endunless %}{% endcapture %}
<li><a href={{ collapse_target }}>{{ title }}{{ expand }}</a><div class="collapse{% if active %} in{% endif %}" id="collapse-{{ i }}"><ul>
{% if this.nav-show_overview %}<li><a href={{ overview_target }}>Overview</a></li>{% endif %}
{% assign elements = elements | push: children %}
{% assign elementsPosStack = elementsPosStack | push: elementsPos %}
{% assign posStack = posStack | push: pos %}

{% assign elementsPos = elements.size | minus: 1 %}
{% assign pos = 0 %}
{% else %}
<li><a href={{ target }}>{{ title }}</a></li>
{% endif %}
{% else %}
<li><a href={{ target }}>{{ title }}</a></li>
{% endif %}
{% endif %}
{% endfor %}
<li class="divider"></li>
<li><a href="http:https://flink.apache.org"><i class="fa fa-external-link" aria-hidden="true"></i> Project Page</a></li>
</ul>

<div class="sidenav-search-box">
<form class="navbar-form" role="search" action="{{site.baseurl}}/search-results.html">
<div class="form-group">
<input type="text" class="form-control" size="16px" name="q" placeholder="Search Docs">
</div>
<button type="submit" class="btn btn-default">Go</button>
</form>
</div>

<div class="sidenav-versions">
<div class="dropdown">
<button class="btn btn-default dropdown-toggle" type="button" data-toggle="dropdown">Pick Docs Version
<span class="caret"></span></button>
<ul class="dropdown-menu">
{% for d in site.previous_docs %}
<li><a href="{{ d[1] }}">v{{ d[0] }}</a></li>
{% endfor %}
</ul>
</div>
</div>
Loading

0 comments on commit 844c874

Please sign in to comment.