GitHub user uce opened a pull request:
https://github.com/apache/flink/pull/1499
[FLINK-3132] [docs] Initial docs restructure
This PR restructures the documentation by allowing pages with
sub-navigations and furthermore fixes some minor issues and adds small
utilities.
A preview can be found here: http://uce.github.io/flink
The goal of the changes is to increase readability in terms of structure
and layout. The content has not been touched (except for minor things like
typos etc.)
## Main Changes
### Streaming and Batch Guide
The links under `Programming Guides` were intermixed with both streaming
and batch docs, for example we currently have the following mixed points:
`DataSet API`, `DataStream API`, `Python API`, `Fault Tolerance` (for both
streaming and batch), `State in Streaming Programs`, `Interactive Scala Shell`,
`DataSet Transformations`, etc. This was kind of confusing. With this PR, the
streaming and batch docs have been grouped to a `Streaming Guide` and `Batch
Guide` respectively.
The respective links have been removed from the top level navigation. If
you look at the preview, open the programming guides drop down and compare.
Futhermore, it's now very easy to add new top level or sub level elements
(see `README.md`).
### Layout changes
Some people complained that the text was too small. This has been addressed
and the per page table of contents has been narrowed down a little as well. The
default text is now a little larger. An issue with the responsiveness (where
the top level elements would wrap a line) has also been addressed.
### Removed content
Removed the TEZ guide, and HDFS and SSH setup instructions from the cluster
setup guide. I would like to remove the bundled examples page from the Batch
guide as a follow up as well.
## Follow Ups and Know Issues
There are plenty of follow ups, which I would like to file JIRAs for after
this is merged.
- Improve getting started guide on the front page
- Simplify stack figure (Remove embedded, Tez, Optimizer, Stream Builder)
- Guide the user to interesting pages
- Improve quick starts (ready to run packages, demo scripts, etc.)
- Make docs streaming first (many parts treat batch first)
- Fine-grained restructuring of streaming guide content (separate page for
windowing, state, etc.)
- Fine-grained review of content
- Known Issue: Flink ML inserts some whitespace due to Latex scripts (?)
- Known Issue: Check code example code style
---
**The main question for this PR is whether you agree with the restructuring
and layout. It would be great to merge this as soon as possible and then
address all follow ups until the 1.0 release.**
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/uce/flink docs_restructure
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/flink/pull/1499.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 #1499
----
commit 35de514544fb1bdde13253283a6f35ee06b1af60
Author: Ufuk Celebi <[email protected]>
Date: 2015-12-24T00:19:02Z
[FLINK-3132] [docs] Initial docs restructure
----
---
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.
---
