website/_dev/howto_docs.md - kylin - Git at Google

 ---
 layout: dev
 title:  How to Write Document
 categories: development
 permalink: /development/howto_docs.html
 ---

 We write documents in MD format and convert to HTML using [Jekyll](http://jekyllrb.com). The Jekyll generated HTML gets uploaded to apache SVN and becomes Kylin website. All MD source files are managed in git so all changes and contributors are clearly tracked.

 ## Before your work

 Before you add or edit documentation, please deploy the document compilation environment. We provide two ways:

 - [Deploy a local document compilation environment](#Deploy a local document compilation environment)
 - [Use Docker to deploy document compilation environment](#Use Docker to deploy document compilation environment)

 ### <span id="Deploy a local document compilation environment">Deploy a local document compilation environment</span>

 Install following tools before you add or edit documentation:

 1. First, make sure Ruby and Gem work on your machine
 	* For Mac user, please refer [this](https://github.com/sstephenson/rbenv#homebrew-on-mac-os-x) to setup ruby env.
 	* For Windows user, use the [ruby installer](http://rubyinstaller.org/downloads/).
 	* For China user, consider use a [local gem repository](https://ruby.taobao.org/) in case of network issues.

 2. Then, install [Jekyll](http://jekyllrb.com), and required plugins
 	* `gem install jekyll jekyll-multiple-languages kramdown rouge`
 	* __Note__: Some specific version of jekyll and jekyll-multiple-languages does not work together (I got a "undefined method" error with jekyll 3.0.1 and jekyll-multiple-languages 2.0.3). In that case, `jekyll 2.5.3` and `jekyll-multiple-languages 1.0.8` is the known working version.
         * eg. Use `gem install jekyll --version "=2.5.3"` to install a specific version.
 	* __Note__: For Mac user, if gem install raise error like this 'ERROR:  While executing gem ... (Gem::FilePermissionError)'. To solve this problem you can use 'brew install ruby', then restart you terminal.
 3. And optionally any markdown editor you prefer

 Below is a gem list that works. Stick to these versions if jekyll installation becomes a problem.

 ```
 $ gem list

 ...
 jekyll (2.5.3)
 jekyll-coffeescript (1.0.1)
 jekyll-gist (1.4.0)
 jekyll-multiple-languages (1.0.8)
 jekyll-paginate (1.1.0)
 jekyll-sass-converter (1.4.0)
 jekyll-watch (1.3.1)
 json (1.8.1)
 kramdown (1.9.0)
 ...
 rouge (1.10.1)
 ...
 ```

 ### <span id="Use Docker to deploy document compilation environment">Use Docker to deploy document compilation environment</span>

 The latest kylin release provides dockerfile, to reduce build complexity using docker and Makefile can call docker command.

 ```
 $ pwd
 /Users/<username>/kylin/website
 $ make docker.build
 docker build -f Dockerfile -t kylin-document:latest .
 Sending build context to Docker daemon  82.44MB
 Step 1/3 : FROM jekyll/jekyll:2.5.3
  ---> e81842c29599
 Step 2/3 : RUN gem install jekyll-multiple-languages -v 1.0.11
  ---> Using cache
  ---> e9e8b0f1d388
 Step 3/3 : RUN gem install rouge -v 3.0.0
  ---> Using cache
  ---> 1bd42c6b93c0
 Successfully built 1bd42c6b93c0
 Successfully tagged kylin-document:latest
 $ make runserver
 docker run --volume="/Users/<username>/kylin/website:/srv/jekyll" -p 4000:4000 --rm -it kylin-document:latest jekyll server --watch
 Configuration file: /srv/jekyll/_config.yml
             Source: /srv/jekyll
        Destination: /srv/jekyll/_site
       Generating...
 ...
 ```

 ## About Jekyll
 Jekyll is a Ruby script to generate a static HTML website from source text and themes, the HTML is generated before being deployed to the web server. Jekyll also happens to be the engine behind GitHub Pages.

 Apache Kylin's website and documentation is using Jekyll to manage and generate final content which avaliable at [http://kylin.apache.org](http://kylin.apache.org).

 ## Multi-Language
 To draft Chinese version document or translate existing one, just add or copy that doc and name with .cn.md as sufffix. It will generate under /cn folder with same name as html file.
 To add other language, please update _config.yml and follow the same pattern as Chinese version.

 ## Kylin document structure and navigation menu

 The Kylin [website as the Jekyll source](https://github.com/apache/kylin/tree/document/website) is maintained under the `doucment` branch.

 1. __Home Page__: _"index.md"_ Home page of Docs
 2. __Getting Started__: _"gettingstarted"_ General docs about Apache Kylin, including FAQ, Terminology
 3. __Installation__: _"install"_ Apache Kylin installation guide
 4. __Tutorial__: _"tutorial"_ User tutorial about how to use Apache Kylin
 5. __How To__: _"howto"_ Guide for more detail help
 6. __Development__: _"development"_ For developer to contribute, integration with other application and extend Apache Kylin
 7. __Others__: Other docs.

 The menu is managed by Jekyll collection:

 * ___data/docs.yml__: English version menu structure
 * ___data/docs-cn.yml__: Chinese version menu structure
 * __add new menu item__: To add new item: create new docs under relative folder, e.g howto_example.md. add following Front Mark:

 ```
 ---
 layout: docs
 title:  How to expamle
 categories: howto
 permalink: /docs/howto/howto_example.html
 version: v0.7.2
 since: v0.7.2
 ---
 ```

 change the __permalink__ to exactly link
 Then add item to docs.yml like:

 ```
 - title: How To
   docs:
   - howto/howto_contribute
   - howto/howto_jdbc
   - howto/howto_example
 ```

 ## How to edit document
 Open doc with any markdown editor, draft content and preview in local.

 Sample Doc:

 ```
 ---
 layout: docs
 title:  How to example
 categories: howto
 permalink: /docs/howto/howto_example.html
 version: v0.7.2
 since: v0.7.2
 ---

 ## This is example doc
 The quick brown fox jump over the lazy dog.
 ```

 ## How to add image
 All impage please put under _images_ folder, in your document, please using below sample to include image:

 ```
 ![](/images/Kylin-Web-Tutorial/2 tables.png)
 ```

 ## How to add link
 Using relative path for site links, for example:

 ```
 [REST API](docs/development/rest_api.html).
 ```

 ## How to add code highlight
 We are using [Rouge](https://github.com/jneen/rouge) to highlight code syntax.
 check this doc's source code for more detail sample.

 ## How to preview in your local
 You can preview in your markdown editor, to check exactly what it will looks like on website, please run Jekyll from `website` folder:

 ```
 jekyll server
 ```
 Then access http://127.0.0.1:4000 in your browser.

 ## How to publish to website (for committer only)

 ### Setup

 1. `cd website`
 2. `svn co https://svn.apache.org/repos/asf/kylin/site _site`

 ___site__ folder is working dir which will be removed anytime by maven or git, please make sure only check out from svn when you want to publish to website.

 ### Running locally
 Before opening a pull request or push to git repo, you can preview changes from your local box with following:

 1. `cd website`
 2. `jekyll s`
 3. Open [http://127.0.0.1:4000](http://127.0.0.1:4000) in your browser

 ### Pushing to site

 1. Copy jekyll generated `_site` to svn `website/_site`
 2. `cd website/_site`
 3. `svn status`
 4. You will need to `svn add` any new files
 5. `svn commit -m 'UPDATE MESSAGE'`

 Within a few minutes, svnpubsub should kick in and you'll be able to
 see the results at
 [http://kylin.apache.org](http://kylin.apache.org/).
	---
	layout: dev
	title: How to Write Document
	categories: development
	permalink: /development/howto_docs.html
	---

	We write documents in MD format and convert to HTML using [Jekyll](http://jekyllrb.com). The Jekyll generated HTML gets uploaded to apache SVN and becomes Kylin website. All MD source files are managed in git so all changes and contributors are clearly tracked.

	## Before your work

	Before you add or edit documentation, please deploy the document compilation environment. We provide two ways:

	- [Deploy a local document compilation environment](#Deploy a local document compilation environment)
	- [Use Docker to deploy document compilation environment](#Use Docker to deploy document compilation environment)

	### <span id="Deploy a local document compilation environment">Deploy a local document compilation environment</span>

	Install following tools before you add or edit documentation:

	1. First, make sure Ruby and Gem work on your machine
	* For Mac user, please refer [this](https://github.com/sstephenson/rbenv#homebrew-on-mac-os-x) to setup ruby env.
	* For Windows user, use the [ruby installer](http://rubyinstaller.org/downloads/).
	* For China user, consider use a [local gem repository](https://ruby.taobao.org/) in case of network issues.

	2. Then, install [Jekyll](http://jekyllrb.com), and required plugins
	* `gem install jekyll jekyll-multiple-languages kramdown rouge`
	* __Note__: Some specific version of jekyll and jekyll-multiple-languages does not work together (I got a "undefined method" error with jekyll 3.0.1 and jekyll-multiple-languages 2.0.3). In that case, `jekyll 2.5.3` and `jekyll-multiple-languages 1.0.8` is the known working version.
	* eg. Use `gem install jekyll --version "=2.5.3"` to install a specific version.
	* __Note__: For Mac user, if gem install raise error like this 'ERROR: While executing gem ... (Gem::FilePermissionError)'. To solve this problem you can use 'brew install ruby', then restart you terminal.
	3. And optionally any markdown editor you prefer

	Below is a gem list that works. Stick to these versions if jekyll installation becomes a problem.

	```
	$ gem list

	...
	jekyll (2.5.3)
	jekyll-coffeescript (1.0.1)
	jekyll-gist (1.4.0)
	jekyll-multiple-languages (1.0.8)
	jekyll-paginate (1.1.0)
	jekyll-sass-converter (1.4.0)
	jekyll-watch (1.3.1)
	json (1.8.1)
	kramdown (1.9.0)
	...
	rouge (1.10.1)
	...
	```

	### <span id="Use Docker to deploy document compilation environment">Use Docker to deploy document compilation environment</span>

	The latest kylin release provides dockerfile, to reduce build complexity using docker and Makefile can call docker command.

	```
	$ pwd
	/Users/<username>/kylin/website
	$ make docker.build
	docker build -f Dockerfile -t kylin-document:latest .
	Sending build context to Docker daemon 82.44MB
	Step 1/3 : FROM jekyll/jekyll:2.5.3
	---> e81842c29599
	Step 2/3 : RUN gem install jekyll-multiple-languages -v 1.0.11
	---> Using cache
	---> e9e8b0f1d388
	Step 3/3 : RUN gem install rouge -v 3.0.0
	---> Using cache
	---> 1bd42c6b93c0
	Successfully built 1bd42c6b93c0
	Successfully tagged kylin-document:latest
	$ make runserver
	docker run --volume="/Users/<username>/kylin/website:/srv/jekyll" -p 4000:4000 --rm -it kylin-document:latest jekyll server --watch
	Configuration file: /srv/jekyll/_config.yml
	Source: /srv/jekyll
	Destination: /srv/jekyll/_site
	Generating...
	...
	```

	## About Jekyll
	Jekyll is a Ruby script to generate a static HTML website from source text and themes, the HTML is generated before being deployed to the web server. Jekyll also happens to be the engine behind GitHub Pages.

	Apache Kylin's website and documentation is using Jekyll to manage and generate final content which avaliable at [http://kylin.apache.org](http://kylin.apache.org).

	## Multi-Language
	To draft Chinese version document or translate existing one, just add or copy that doc and name with .cn.md as sufffix. It will generate under /cn folder with same name as html file.
	To add other language, please update _config.yml and follow the same pattern as Chinese version.

	## Kylin document structure and navigation menu

	The Kylin [website as the Jekyll source](https://github.com/apache/kylin/tree/document/website) is maintained under the `doucment` branch.

	1. __Home Page__: _"index.md"_ Home page of Docs
	2. __Getting Started__: _"gettingstarted"_ General docs about Apache Kylin, including FAQ, Terminology
	3. __Installation__: _"install"_ Apache Kylin installation guide
	4. __Tutorial__: _"tutorial"_ User tutorial about how to use Apache Kylin
	5. __How To__: _"howto"_ Guide for more detail help
	6. __Development__: _"development"_ For developer to contribute, integration with other application and extend Apache Kylin
	7. __Others__: Other docs.

	The menu is managed by Jekyll collection:

	* ___data/docs.yml__: English version menu structure
	* ___data/docs-cn.yml__: Chinese version menu structure
	* __add new menu item__: To add new item: create new docs under relative folder, e.g howto_example.md. add following Front Mark:

	```
	---
	layout: docs
	title: How to expamle
	categories: howto
	permalink: /docs/howto/howto_example.html
	version: v0.7.2
	since: v0.7.2
	---
	```

	change the __permalink__ to exactly link
	Then add item to docs.yml like:

	```
	- title: How To
	docs:
	- howto/howto_contribute
	- howto/howto_jdbc
	- howto/howto_example
	```

	## How to edit document
	Open doc with any markdown editor, draft content and preview in local.

	Sample Doc:

	```
	---
	layout: docs
	title: How to example
	categories: howto
	permalink: /docs/howto/howto_example.html
	version: v0.7.2
	since: v0.7.2
	---

	## This is example doc
	The quick brown fox jump over the lazy dog.
	```

	## How to add image
	All impage please put under _images_ folder, in your document, please using below sample to include image:

	```
	![](/images/Kylin-Web-Tutorial/2 tables.png)
	```

	## How to add link
	Using relative path for site links, for example:

	```
	[REST API](docs/development/rest_api.html).
	```

	## How to add code highlight
	We are using [Rouge](https://github.com/jneen/rouge) to highlight code syntax.
	check this doc's source code for more detail sample.

	## How to preview in your local
	You can preview in your markdown editor, to check exactly what it will looks like on website, please run Jekyll from `website` folder:

	```
	jekyll server
	```
	Then access http://127.0.0.1:4000 in your browser.

	## How to publish to website (for committer only)

	### Setup

	1. `cd website`
	2. `svn co https://svn.apache.org/repos/asf/kylin/site _site`

	___site__ folder is working dir which will be removed anytime by maven or git, please make sure only check out from svn when you want to publish to website.

	### Running locally
	Before opening a pull request or push to git repo, you can preview changes from your local box with following:

	1. `cd website`
	2. `jekyll s`
	3. Open [http://127.0.0.1:4000](http://127.0.0.1:4000) in your browser

	### Pushing to site

	1. Copy jekyll generated `_site` to svn `website/_site`
	2. `cd website/_site`
	3. `svn status`
	4. You will need to `svn add` any new files
	5. `svn commit -m 'UPDATE MESSAGE'`

	Within a few minutes, svnpubsub should kick in and you'll be able to
	see the results at
	[http://kylin.apache.org](http://kylin.apache.org/).