documentation.kii.com

Before starting.

Before starting please read about Jekyll.

To execute jekyll on your PC, which require:

• ruby 1.9.3-p392 or above: 2.0.0-p0 recommended to free from stress.
• jekyll and redcarpet
• python 2.7.4 or above

Install instruction.

1. Install ruby.

   For Windows: use RubyInstaller. Install ruby core and devkit.

   For others: See your OS package system.

2. Install jekyll and redcarpet.

   $ gem install jekyll
   $ gem install redcarpet
   

   For Windows: recommended to downgrade directory_watcher module.

   $ gem install directory_watcher -v 1.4.1
   $ gem uninstall directory_watcher -v 1.5.1
   

3. Install python.

   It is used by syntax highlighting (pygment.rb)

Usage

Just type jekyll. It generate/update all files into _site/ directory. It tooks several times (maximum about 1min). To release those, transfer all files in _site/ to public server.

To see your changes on local machine try this.

for jekyll 1.0 or above

$ jekyll server --watch

for jekyll 0.12

$ jekyll --auto --server

Then open http://127.0.0.1:4000/ by using your favorite WEB browser.

Editing work flow.

Please check files and directories and files under en/ and ja/ directories.

Here are some explanations to help you understand how to edit pages.

Importatnt: Be sure that all files are saved with LF line ending (UNIX style).

YAML header

YAML header should be includes:

• layout (mandatory)
• title (mandatory)
• sort-priority (option)
• page-id (option)

layout

use en-doc for English, use ja-doc for Japanese.

sort-priority

The number used as a referece for sorting pages in the same directory. The pages will be aligned in the left side navigator in an ascending order based on this sort-priority number.

page-id

Make page references abstract, we use page-id in YAML header for the most of pages.

page-id consists two or three parts:

{platform}-{title}-{language}

  or

{title}-{language}

Each part should not contain - characters.

An example of two parts page-id (from en/guides.mkd):

---
layout: en-doc
title: Guides
page-id: guides-en
sort-priority: 20
---

An example of three parts page-id (from en/starts/android.mkd):

---
layout: en-doc
title: Android Quick Start
sort-priority: 10
page-id: android-quickstart-en
---

Contents

Write the contents using regular Markdown syntax.

Referring to other pages

Use {% page_link {page-id} %} or {% page_url {page-id} %}.

page_link is expanded to:

<a href="{URL of the target page}">{title of the target page}</a>

See en/samples.mkd for an example of how to use page_link.

page_url is expanded to:

{URL of the target page}

See en.html for an example of page_url.page_url

Deploying the pages to documentation.kii.com

Simply upload everything inside _site. You can use the helper script for this.

for jekyll 1.0 or above

$ jekyll build
$ sh scripts/sync.sh

for jekyll 0.12

$ jekyll
$ sh scripts/sync.sh

Note that you need to know the password.

Tips

• For generating REST documents from WADL files, use the WADL parsing and representation library provided at https://github.com/c0ze/kii-ruby-wadl.

Others

Layout tree

• _layouts/default.html
  • _layouts/en.html
    • _layout/en-doc.html
    • _layout/rest-api.html
  • _layouts/ja.html
    • _layouts/ja-doc.html

Helper scripts

Generated Pages Uploader

for jekyll 1.0 or above

$ jekyll build
$ sh scripts/sync.sh

Symmetrical Files Checker

$ sh scripts/symmetrical_check.sh en ja

$ sh scripts/symmetrical_check.sh en/starts/android en/starts/ios

$ sh scripts/symmetrical_check.sh {dir1} {dir2}