enhance the doc for personal rank & add a simple case (apache#92)

clients/restful-api/rank.md

@@ -7,10 +7,17 @@ HugeGraphServer 除了上一节提到的遍历（traverser）方法，还提供
 
 #### 4.2.1 Personal Rank API
 
+Personal Rank 算法典型场景是用于推荐应用中, 根据某个点现有的出边, 推荐具有相近 / 相同关系的其他点,
+比如根据某个人的阅读记录 / 习惯, 向它推荐其他可能感兴趣的书, 或潜在的书友, 举例如下:
+1. 假设给定 1个 Person 点 是 tom, 它喜欢 `a,b,c,d,e` 5本书, 我们的想给 tom 推荐一些书友, 以及一些书, 最容易的想法就是看看还有哪些人喜欢过这些书 (共同兴趣)
+2. 那么此时, 需要有其它的 Person 点比如 neo, 他喜欢 `b,d,f` 3本书, 以及 jay, 它喜欢 `c,d,e,g` 4本书, lee 它喜欢 `a,d,e,f` 4本书
+3. 由于 tom 已经看过的书不需要重复推荐, 所以返回结果里应该期望推荐有共同喜好的其他书友看过, 但 tom 没看过的书, 比如推荐 "f"  和 "g" 书, 且优先级 f > g
+4. 此时再计算 tom 的个性化 rank 值, 就会返回排序后 TopN 推荐的 书友 + 书 的结果了 (如果只需要推荐的书, 选择 OTHER_LABEL 即可)
+
 ##### 4.2.1.0 数据准备
 
-这里以[MovieLens](https://grouplens.org/datasets/movielens/)的 1M 数据集为例，用户需
-下载该数据集，然后使用 HugeGraph-Loader 导入到 HugeGraph 中，为简单起见，数据中顶点 user 
+上面是一个简单的例子, 这里再提供一个公开的 1MB 测试数据集 [MovieLens](https://grouplens.org/datasets/movielens/) 为例，
+用户需下载该数据集，然后使用 HugeGraph-Loader 导入到 HugeGraph 中，简单起见，数据中顶点 user 
 和 movie 的属性都忽略，仅使用 id 字段即可，边 rating 的具体评分值也忽略。loader 使用的元数据
 文件和输入源映射文件内容如下：
 
@@ -110,25 +117,29 @@ schema.edgeLabel("rating")
 假设有一个用户和物品的二分图，基于随机游走的 PersonalRank 算法步骤如下：
 
 1. 选定一个起点用户 u，其初始权重为 1.0，从 Vu 开始游走（有 alpha 的概率走到邻居点，1 - alpha 的概率停留）；
-2. 如果决定游走：
-    2.1. 那就从当前节点的邻居节点中按照均匀分布随机选择一个，并且按照均匀分布划分权重值；
-    2.2. 给源顶点补偿权重 1 - alpha；
-    2.3. 重复步骤2；
-3. 达到一定步数后收敛，得到推荐列表。
+2. 如果决定向外游走, 那么会选取某一个类型的出边, 例如 `rating` 来查找共同的打分人：
+   1. 那就从当前节点的邻居节点中按照均匀分布随机选择一个，并且按照均匀分布划分权重值；
+   2. 给源顶点补偿权重 1 - alpha；
+   3. 重复步骤2；
+3. 达到一定步数或达到精度后收敛，得到推荐列表。
 
 ###### Params
 
-- source: 源顶点 id，必填项
-- label: 边的类型，必须是连接两类不同顶点的边，必填项
-- alpha：每轮迭代时从某个点往外走的概率，与 PageRank 算法中的 alpha 类似，必填项，取值区间为 (0, 1] 
-- max_degree: 查询过程中，单个顶点遍历的最大邻接边数目，选填项，默认为 10000
-- max_depth: 迭代次数，必填项，取值区间为 (0, 50] 
-- with_label：筛选结果中保留哪些结果，选填项，可选值为 [SAME_LABEL, OTHER_LABEL, BOTH_LABEL], 默认为 BOTH_LABEL
-    - SAME_LABEL：保留与源顶点相同类别的顶点
-    - OTHER_LABEL：保留与源顶点不同类别（二分图的另一端）的顶点
-    - BOTH_LABEL：保留与源顶点相同和相反类别的顶点
-- limit: 返回的顶点的最大数目，选填项，默认为 10000000
-- sorted：返回的结果是否根据 rank 排序，为 true 时降序排列，反之不排序，选填项，默认为 true
+**必填项**:
+- source: 源顶点 id
+- label: 源点出发的某类边 label，须连接两类不同顶点
+
+**选填项**:
+- alpha：每轮迭代时从某个点往外走的概率，与 PageRank 算法中的 alpha 类似，取值区间为 (0, 1], 默认值 `0.85` 
+- max_degree: 查询过程中，单个顶点遍历的最大邻接边数目，默认为 `10000`
+- max_depth: 迭代次数，取值区间为 [2, 50], 默认值 `5`
+- with_label：筛选结果中保留哪些结果，可选以下三类, 默认为 `BOTH_LABEL`
+    - SAME_LABEL：仅保留与源顶点相同类别的顶点
+    - OTHER_LABEL：仅保留与源顶点不同类别（二分图的另一端）的顶点
+    - BOTH_LABEL：同时保留与源顶点相同和相反类别的顶点
+- limit: 返回的顶点的最大数目，默认为 `100`
+- max_diff: 提前收敛的精度差, 默认为 `0.0001` (*后续实现*)  
+- sorted：返回的结果是否根据 rank 排序，为 true 时降序排列，反之不排序，默认为 `true`
 
 ##### 4.2.1.2 使用方法
 
@@ -179,7 +190,9 @@ POST http://localhost:8080/graphs/hugegraph/traversers/personalrank
 
 两类不同顶点连接形成的二分图中，给某个点推荐相关性最高的其他顶点，例如：
 
-- 商品推荐中，查找最应该给某人推荐的商品列表
+- 阅读推荐: 找出优先给某人推荐的其他**书籍**, 也可以同时推荐共同喜好最高的**书友** (例: 微信 "你的好友也在看 xx 文章" 功能)
+- 社交推荐: 找出拥有相同关注话题的其他**博主**, 也可以推荐可能感兴趣的**新闻/消息** (例: Weibo 中的 "热点推荐" 功能)
+- 商品推荐: 通过某人现在的购物习惯, 找出应优先推给它的**商品列表**, 也可以给它推荐**带货**播主 (例: TaoBao 的 "猜你喜欢" 功能)
 
 #### 4.2.2 Neighbor Rank API
 

clients/restful-api/traverser.md

@@ -248,20 +248,20 @@ GET http://localhost:8080/graphs/{graph}/traversers/kout?source="1:marko"&max_de
 
 - source：起始顶点id，必填项
 - 从起始点出发的Step，必填项，结构如下：
-	- direction：表示边的方向（OUT,IN,BOTH），默认是BOTH
-	- labels：边的类型列表
-	- properties：通过属性的值过滤边
-	- max_degree：查询过程中，单个顶点遍历的最大邻接边数目，默认为 10000 (注: 0.12版之前 step 内仅支持 degree 作为参数名, 0.12开始统一使用 max_degree, 并向下兼容 degree 写法)
-	- skip_degree：用于设置查询过程中舍弃超级顶点的最小边数，即当某个顶点的邻接边数目大于 skip_degree 时，完全舍弃该顶点。选填项，如果开启时，需满足 `skip_degree >= max_degree` 约束，默认为0 (不启用)，表示不跳过任何点 (注意:  开启此配置后，遍历时会尝试访问一个顶点的 skip_degree 条边，而不仅仅是 max_degree 条边，这样有额外的遍历开销，对查询性能影响可能有较大影响，请确认理解后再开启)
+    - direction：表示边的方向（OUT,IN,BOTH），默认是BOTH
+    - labels：边的类型列表
+    - properties：通过属性的值过滤边
+    - max_degree：查询过程中，单个顶点遍历的最大邻接边数目，默认为 10000 (注: 0.12版之前 step 内仅支持 degree 作为参数名, 0.12开始统一使用 max_degree, 并向下兼容 degree 写法)
+    - skip_degree：用于设置查询过程中舍弃超级顶点的最小边数，即当某个顶点的邻接边数目大于 skip_degree 时，完全舍弃该顶点。选填项，如果开启时，需满足 `skip_degree >= max_degree` 约束，默认为0 (不启用)，表示不跳过任何点 (注意:  开启此配置后，遍历时会尝试访问一个顶点的 skip_degree 条边，而不仅仅是 max_degree 条边，这样有额外的遍历开销，对查询性能影响可能有较大影响，请确认理解后再开启)
 - max_depth：步数，必填项
 - nearest：nearest为true时，代表起始顶点到达结果顶点的最短路径长度为depth，不存在更短的路径；nearest为false时，代表起始顶点到结果顶点有一条长度为depth的路径（未必最短且可以有环），选填项，默认为true
 - count_only：Boolean值，true表示只统计结果的数目，不返回具体结果；false表示返回具体的结果，默认为false
 - with_path：true表示返回起始点到每个邻居的最短路径，false表示不返回起始点到每个邻居的最短路径，选填项，默认为false
 - with_vertex，选填项，默认为false：
-	- true表示返回结果包含完整的顶点信息（路径中的全部顶点）
-		- with_path为true时，返回所有路径中的顶点的完整信息
-		- with_path为false时，返回所有邻居的完整信息
-	- false时表示只返回顶点id
+    - true表示返回结果包含完整的顶点信息（路径中的全部顶点）
+        - with_path为true时，返回所有路径中的顶点的完整信息
+        - with_path为false时，返回所有邻居的完整信息
+    - false时表示只返回顶点id
 - capacity：遍历过程中最大的访问的顶点数目，选填项，默认为10000000
 - limit：返回的顶点的最大数目，选填项，默认为10000000
 
@@ -450,19 +450,19 @@ GET http://localhost:8080/graphs/{graph}/traversers/kneighbor?source=“1:marko
 
 - source：起始顶点id，必填项
 - 从起始点出发的Step，必填项，结构如下：
-	- direction：表示边的方向（OUT,IN,BOTH），默认是BOTH
-	- labels：边的类型列表
-	- properties：通过属性的值过滤边
-	- max_degree：查询过程中，单个顶点遍历的最大邻接边数目，默认为 10000 (注: 0.12版之前 step 内仅支持 degree 作为参数名, 0.12开始统一使用 max_degree, 并向下兼容 degree 写法)
-	- skip_degree：用于设置查询过程中舍弃超级顶点的最小边数，即当某个顶点的邻接边数目大于 skip_degree 时，完全舍弃该顶点。选填项，如果开启时，需满足 `skip_degree >= max_degree` 约束，默认为0 (不启用)，表示不跳过任何点 (注意:  开启此配置后，遍历时会尝试访问一个顶点的 skip_degree 条边，而不仅仅是 max_degree 条边，这样有额外的遍历开销，对查询性能影响可能有较大影响，请确认理解后再开启)
+    - direction：表示边的方向（OUT,IN,BOTH），默认是BOTH
+    - labels：边的类型列表
+    - properties：通过属性的值过滤边
+    - max_degree：查询过程中，单个顶点遍历的最大邻接边数目，默认为 10000 (注: 0.12版之前 step 内仅支持 degree 作为参数名, 0.12开始统一使用 max_degree, 并向下兼容 degree 写法)
+    - skip_degree：用于设置查询过程中舍弃超级顶点的最小边数，即当某个顶点的邻接边数目大于 skip_degree 时，完全舍弃该顶点。选填项，如果开启时，需满足 `skip_degree >= max_degree` 约束，默认为0 (不启用)，表示不跳过任何点 (注意:  开启此配置后，遍历时会尝试访问一个顶点的 skip_degree 条边，而不仅仅是 max_degree 条边，这样有额外的遍历开销，对查询性能影响可能有较大影响，请确认理解后再开启)
 - max_depth：步数，必填项
 - count_only：Boolean值，true表示只统计结果的数目，不返回具体结果；false表示返回具体的结果，默认为false
 - with_path：true表示返回起始点到每个邻居的最短路径，false表示不返回起始点到每个邻居的最短路径，选填项，默认为false
 - with_vertex，选填项，默认为false：
-	- true表示返回结果包含完整的顶点信息（路径中的全部顶点）
-		- with_path为true时，返回所有路径中的顶点的完整信息
-		- with_path为false时，返回所有邻居的完整信息
-	- false时表示只返回顶点id
+    - true表示返回结果包含完整的顶点信息（路径中的全部顶点）
+        - with_path为true时，返回所有路径中的顶点的完整信息
+        - with_path为false时，返回所有邻居的完整信息
+    - false时表示只返回顶点id
 - limit：返回的顶点的最大数目，选填项，默认为10000000
 
 ##### 3.2.4.2 使用方法

scripts/github-deploy.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-
+set -x
 # this script is for developers to manually deploy doc to GitHub Pages
 REMOTE="github"
 REMOTE_URL="https://github.com/hugegraph/hugegraph-doc"