Add instructions for building website and documentation
Author: Sijie Guo <sijieg@twitter.com>
Author: Sijie Guo <sijie@apache.org>
Reviewers: Leigh Stewart <lstewart@twitter.com>
Closes #30 from sijie/sijie/add_instructions_for_building_website
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..88d8855
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,87 @@
+This README gives an overview of how to build and contribute to the documentation of Apache DistributedLog.
+
+The documentation is included with the source of Apache DistributedLog in order to ensure that you always
+have docs corresponding to your checked out version. The online documentation at
+http://distributedlog.incubator.apache.org/docs/latest is also generated from the files found at master branch.
+
+# Requirements
+
+First, make sure you have Ruby installed. The minimal ruby version is 2.0.0.
+
+The dependencies are declared in the Gemfile in this directory. We use [reStructuredText](http://docutils.sourceforge.net/rst.html)
+to write and [Jekyll](https://jekyllrb.com/) and [jekyll-rst](https://github.com/xdissent/jekyll-rst) to translate the documentation to static HTML.
+You can use Ruby's Bundler Gem to install all the depenencies for building the documentation:
+
+ gem install bundler
+ bundle install
+
+And use [pip](https://pypi.python.org/pypi/pip) to install docutils and pygments
+
+ pip install docutils pygments
+
+# Build
+
+## Live developement
+
+While you are working with the documentation, you can test and develop live. Run the following in the root folder of the `docs`:
+
+ $ bundle exec jekyll serve
+
+Jekyll will start a webserver on port `4000`. As you make changes to the content, Jekyll will rebuild it automatically.
+This is helpful if you want to see how your changes will render in realtime.
+
+## Generating the static website
+
+Once you are done with your changes, you need to compile the static content for the website.
+This is what is actually hosted on the Apache DistributedLog documentation site.
+
+You can build the static content by running the following command in the root docs directory:
+
+ $ jekyll build
+
+Once built, it will be placed in the folder `_site` inside of the root directory. This directory will include images, HTML, CSS, and so on.
+
+# Contribute
+
+## reStructuredText
+
+The documentation pages are written in [reStructuredText](http://docutils.sourceforge.net/rst.html). It is possible to use [Markdown](http://daringfireball.net/projects/markdown/syntax) and intermix plain html.
+
+## Front matter
+
+In addition to Markdown, every page contains a Jekyll front matter, which specifies the title of the page and the layout to use.
+The title is used as the top-level heading for the page.
+
+There are two layouts (found in `_layouts`) used for writing documentation: one is `default`, while the other one is `guide`.
+The pages that use `default` layout will not have navigation side bar, while the pages that use `guide` layout will have
+navigation side bar. The pages under `user-guide` and `admin-guide` are written using `guide` layout.
+
+ ---
+ title: "Title of the Page"
+ layout: default
+ ---
+
+Furthermore, you can access variables found in `docs/_config.yml` as follows:
+
+ {{ site.NAME }}
+
+This will be replaced with the value of the variable called `NAME` when generating the docs.
+
+## Structure
+
+### Documentation
+
+#### Navigation
+
+The navigation on the left side of the docs is automatically generated when building the docs. You can modify the markup in `_layouts/guide.html`.
+
+The structure of the navigation is determined by the front matter of 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_`. There is no limitation on how many levels you can nest.
+
+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`.
+
+The nesting is also used for the breadcrumbs like `User Guide > API > Best Practise`.
diff --git a/website/README.md b/website/README.md
index f07ff10..2efe425 100644
--- a/website/README.md
+++ b/website/README.md
@@ -22,58 +22,40 @@
DistributedLog website.
### Development setup
-Before working with the Jekyll code, you will need to install Jekyll:
- $ gem install jekyll
- $ gem install jekyll-redirect-from
- $ gem install html-proofer
+First, make sure you have Ruby installed. The minimal ruby version is 2.0.0.
+
+Before working with the Jekyll code, you can use Ruby's Bundler Gem to install all the dependencies for building this website:
+
+ gem install bundler
+ bundle install
*If you are on a Mac, you may need to install
[Ruby Gems](https://rubygems.org/pages/download).*
-### Live development
-While you are working with the website, you can test and develop live. Run the
-following command in the root folder of the website:
+And use [pip](https://pypi.python.org/pypi/pip) to install docutils and pygments required for building the documentation:
- $ jekyll serve
+ pip install docutils pygments
-Jekyll will start a webserver on port `4000`. As you make changes to the
-content, Jekyll will rebuild it automatically. This is helpful if you want to see
-how your changes will render in realtime.
+### Build website together with documentation
-In addition, you can run the tests via:
+You can run the `build.sh` at the root folder of `website` to build a local site.
- $ rake test
+ $ build.sh local
-### Generating the static website
-Once you are done with your changes, you need to compile the static
-content for the website. This is what is actually hosted
-on the Apache DistributedLog website.
+You can also build with the production settings. It will generate the content that is actually hosted in distributedlog website.
-You can build the static content by running the following command in the root
-website directory:
+ $ build.sh production
- $ jekyll build
-
-Once built, it will be placed in the folder `content` inside of the root directory.
-This directory will include images, HTML, CSS, and so on. In a typical Jekyll install
-this content would live in `_site` - it has been changed for the Apache DistributedLog website
+Once built, it will be placed in the folder `content` inside of the root directory.
+This directory will include images, HTML, CSS and so on. In a typical Jekyll install
+this content will live in `_site` - it has been changed for Apache DistributedLog website
to work with the ASF Incubator publishing system.
-### Apache License
----
-Except as otherwise noted this software is licensed under the
-[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
+### Run the server locally
-Licensed 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
+You can run `bundle exec jekyll serve` locally to serve the generated static content to verify if the website works as expected.
- http://www.apache.org/licenses/LICENSE-2.0
+ $ bundle exec jekyll serve
-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.
