[GitHub] shaofengshi closed pull request #313: draft for kylin doc spec and modified installation guide

[GitBox <gi...@apache.org>]

shaofengshi closed pull request #313: draft for kylin doc spec and modified installation guide 
URL: https://github.com/apache/kylin/pull/313
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/website/_data/development-cn.yml b/website/_data/development-cn.yml
index d1b2331b53..703286c193 100644
--- a/website/_data/development-cn.yml
+++ b/website/_data/development-cn.yml
@@ -24,6 +24,7 @@
     - howto_test
     - howto_contribute
     - howto_docs
+    - doc_spec
     - howto_package
     - howto_hbase_branches
     - howto_release
diff --git a/website/_dev/doc_spec.cn.md b/website/_dev/doc_spec.cn.md
new file mode 100644
index 0000000000..5fd87ae304
--- /dev/null
+++ b/website/_dev/doc_spec.cn.md
@@ -0,0 +1,89 @@
+---
+layout: dev-cn
+title:  Kylin 文档撰写规范
+categories: development
+permalink: /cn/development/doc_spec.html
+---
+
+
+本文从章节结构、元素标记、用语规范、文件/路径规范等方面对 Kylin 文档的撰写规范进行了详述。
+
+### 准备工作
+
+1. 请您根据 [如何写文档](howto_docs.cn.md) 准备撰写文档有关的环境，了解 Kylin 文档结构。
+2. Kylin 文档使用 Markdown 语法书写，以下简称 md。请您确保您熟悉 [Markdown 语法](https://guides.github.com/features/mastering-markdown/)。
+
+### 章节结构
+
+- 每个章节的内容以多个小节的形式组织，每个小节的标题使用 **Heading 3 样式**。如：
+	\#\#\# 安装 Kylin
+- 如果需要在小节内进一步对内容进行组织，请使用 **无序 / 有序 列表**，尽量不使用 **Heading 4**，完全避免 **Heading 5**。如：
+	\### 安装 Kylin
+	1. 首先，……
+        \* 运行……
+        \* 解压……
+
+### 元素标记
+
+- 粗体
+  使用粗体标记您需要强调的内容。如：
+  1. 强调 GUI 上某个组件的名称。
+  2. 强调一个新概念。
+  3. 强调用户在阅读时容易忽略的否定词。
+
+- 斜体
+  1. 中文文档中一般不使用斜体。
+  2. 英文文档中对于以下情形可以使用斜体，如数据库表名、列名等。
+
+- 引用
+  1. 使用引用来标记 次要信息 / 补充信息，即不影响正常理解和使用的扩展信息。如：
+  	> 您可以继续阅读以获得更多关于……的信息。
+  2. 使用引用来标记 提示信息。
+  	- 对于一般性提示信息，使用 **提示 / Note** 开头。
+  	- 对于关键或警示的提示信息，使用 **注意 / Caution** 开头。
+
+- 行内代码
+  使用行内代码标记一切**可能**会**被用户输入到 shell / config 中的内容**，比如文件路径、 Unix 账户、配置项和值等。
+
+- 代码段
+  使用代码段标记**所有用户需要执行的 shell 命令和 config 配置**，统一格式且需要足够凸显。如：
+
+  1. shell 命令
+  \`\`\`shell
+  $KYLIN_HOME/bin/kylin.sh start
+  \`\`\`
+
+  2. config 配置
+    \`\`\`properties
+    kylin.env.hdfs-working-dir=/kylin
+    \`\`\`
+    \`\`\` xml
+    <property>
+    <name>mapreduce.map.memory.mb</name>
+    <value>2048</value>
+    </property>
+    \`\`\`
+
+
+### 用语规范
+
+- 英文专用词汇
+  - 中文文档中，一般出现的英文词汇都需要使用首字母大写。如：
+  	Cube 概念是指一个 Cuboid 的集合，其中……。
+  - 英文文档中，当第一次出现某个英语专有词汇时，需要将首字母大写，并且用粗体强调，其他时候不需要大写 ”cube“ 或者 ”model“ 等词语。
+
+- 中英文（数字）混合
+  在中文版中，所有出现的英文（数字）需要在两端中英文交界处添加一个**额外英文半角空格**，以增强中英文混排的美观性和可读性。
+- 标点符号
+  - 在中文文档中，**请一律使用中文标点符号**。
+
+- UI 交互的描写
+  1. 统一对页面元素的称呼。
+    顶部状态栏 / the top header
+    左侧导航栏 / the left navigation
+    xxx 页面 / the xxx page
+    xxx 面板 / the xxx panel
+    xxx 对话框 / the xxx dialog
+  2. 用**加粗样式**强调交互元素。如：
+    点击\*\*提交\*\*按钮。
+  3. 用 **->** 说明连续操作。
\ No newline at end of file
diff --git a/website/_docs/install/index.cn.md b/website/_docs/install/index.cn.md
index c6931c32f4..9c784f2cfa 100644
--- a/website/_docs/install/index.cn.md
+++ b/website/_docs/install/index.cn.md
@@ -5,7 +5,7 @@ categories: install
 permalink: /cn/docs/install/index.html
 ---
 
-## 软件要求
+### 软件要求
 
 * Hadoop: 2.7+, 3.1+ (since v2.5)
 * Hive: 0.13 - 1.2.1+
@@ -17,63 +17,75 @@ permalink: /cn/docs/install/index.html
 
 在 Hortonworks HDP 2.2 - 2.6 and 3.0, Cloudera CDH 5.7 - 5.11 and 6.0, AWS EMR 5.7 - 5.10, Azure HDInsight 3.5 - 3.6 上测试通过。
 
-出于试用和开发的目的，我们建议您使用集成的 sandbox 来试用 Kylin，比如 [HDP sandbox](http://hortonworks.com/products/hortonworks-sandbox/)，且其要保证 10 GB memory。我们建议您在 Virtual Box settings 中使用桥接模式代替 NAT 模式。 
+我们建议您使用集成的 sandbox 来试用 Kylin 或进行开发，比如 [HDP sandbox](http://hortonworks.com/products/hortonworks-sandbox/)，且要保证其有至少 10 GB 内存。在配置沙箱时，我们推荐您使用 Bridged Adapter 模型替代 NAT 模型。
 
-## 硬件要求
+### 硬件要求
 
-运行 Kylin 的服务器的最低的配置为 4 core CPU, 16 GB memory 和 100 GB disk。 对于高负载的场景，建议使用 24 core CPU, 64 GB memory 或更高的配置。
+运行 Kylin 的服务器的最低配置为 4 core CPU，16 GB 内存和 100 GB 磁盘。 对于高负载的场景，建议使用 24 core CPU，64 GB 内存或更高的配置。
 
 
-## Hadoop 环境
+### Hadoop 环境
 
-Kylin 依赖于 Hadoop 集群处理大量的数据集。您需要准备一个配置好 HDFS, YARN, MapReduce, Hive, Hbase, Zookeeper 和其他服务的 Hadoop 集群供 Kylin 运行。最常见的是在 Hadoop client machine 上安装 Kylin，这样 Kylin 可以通过（`hive`, `hbase`, `hadoop`, 以及其他的）命令行与 Hadoop 进行通信。 
+Kylin 依赖于 Hadoop 集群处理大量的数据集。您需要准备一个配置好 HDFS，YARN，MapReduce,，Hive， HBase，Zookeeper 和其他服务的 Hadoop 集群供 Kylin 运行。
+Kylin 可以在 Hadoop 集群的任意节点上启动。方便起见，您可以在 master 节点上运行 Kylin。但为了更好的稳定性，我们建议您将 Kylin 部署在一个干净的 Hadoop client 节点上，该节点上 Hive，HBase，HDFS 等命令行已安装好且 client 配置（如 `core-site.xml`，`hive-site.xml`，`hbase-site.xml`及其他）也已经合理的配置且其可以自动和其它节点同步。
 
-Kylin 可以在 Hadoop 集群的任意节点上启动。方便起见，您可以在 master 节点上运行 Kylin。但为了更好的稳定性，我们建议您将其部署在一个干净的 Hadoop client 节点上，该节点上 `hive`, `hbase`, `hadoop`, `hdfs` 命令行已安装好且 client 配置如（core-site.xml, hive-site.xml, hbase-site.xml, 及其他）也已经合理的配置且其可以自动和其它节点同步。运行 Kylin 的 Linux 账户要有访问 Hadoop 集群的权限，包括 create/write HDFS 文件夹, hive 表, hbase 表 和 提交 MR jobs 的权限。 
+运行 Kylin 的 Linux 账户要有访问 Hadoop 集群的权限，包括创建/写入 HDFS 文件夹，Hive 表， HBase 表和提交 MapReduce 任务的权限。 
 
-## Kylin 安装
+### Kylin 安装
 
- * 从最新的 Apache 下载网站下载一个适用于您 Hadoop 版本的 Kylin binaries 文件。例如，来源于 US 适用于 HBase 1.x 的 Kylin 2.3.1:
-{% highlight Groff markup %}
-cd /usr/local
-wget http://www-us.apache.org/dist/kylin/apache-kylin-2.3.1/apache-kylin-2.3.1-hbase1x-bin.tar.gz
-{% endhighlight %}
- * 解压 tar 包，然后配置环境变量 KYLIN_HOME 指向 Kylin 文件夹
-{% highlight Groff markup %}
-tar -zxvf apache-kylin-2.3.1-hbase1x-bin.tar.gz
-cd apache-kylin-2.3.1-bin
+1. 从 [Apache Kylin下载网站](https://kylin.apache.org/download/) 下载一个适用于您 Hadoop 版本的二进制文件。例如，适用于 HBase 1.x 的 Kylin 2.5.0 可通过如下命令行下载得到：
+
+```shell
+cd /usr/local/
+wget http://mirror.bit.edu.cn/apache/kylin/apache-kylin-2.5.0/apache-kylin-2.5.0-bin-hbase1x.tar.gz
+```
+
+2. 解压 tar 包，配置环境变量 `$KYLIN_HOME` 指向 Kylin 文件夹
+
+```shell
+tar -zxvf apache-kylin-2.5.0-bin-hbase1x.tar.gz
+cd apache-kylin-2.5.0-bin-hbase1x
 export KYLIN_HOME=`pwd`
-{% endhighlight %}
- * 确保用户有权限在 shell 中运行 hadoop, hive 和 hbase cmd。如果您不确定，您可以运行 `$KYLIN_HOME/bin/check-env.sh` 脚本，如果您的环境有任何的问题，它会将打印出详细的信息。如果没有 error，意味着环境没问题。
-{% highlight Groff markup %}
--bash-4.1# $KYLIN_HOME/bin/check-env.sh
-Retrieving hadoop conf dir...
-KYLIN_HOME is set to /usr/local/apache-kylin-2.3.1-bin
--bash-4.1#
-{% endhighlight %}
- * 运行 `$KYLIN_HOME/bin/kylin.sh start` 脚本来启动 Kylin，服务器启动后，您可以通过查看 `$KYLIN_HOME/logs/kylin.log` 获得运行时日志。
-{% highlight Groff markup %}
--bash-4.1# $KYLIN_HOME/bin/kylin.sh start
-Retrieving hadoop conf dir...
-KYLIN_HOME is set to /usr/local/apache-kylin-2.3.1-bin
-Retrieving hive dependency...
-Retrieving hbase dependency...
+```
+
+
+### 检查运行环境
+
+Kylin 运行在 Hadoop 集群上，对各个组件的版本、访问权限及 CLASSPATH 等都有一定的要求，为了避免遇到各种环境问题，您可以运行 `$KYLIN_HOME/bin/check-env.sh` 脚本来进行环境检测，如果您的环境存在任何的问题，脚本将打印出详细报错信息。如果没有报错信息，代表您的环境适合 Kylin 运行。
+
+
+### 启动 Kylin
+
+运行 `$KYLIN_HOME/bin/kylin.sh start` 脚本来启动 Kylin，界面输出如下：
+
+```
 Retrieving hadoop conf dir...
-Retrieving kafka dependency...
-Retrieving Spark dependency...
-...
+KYLIN_HOME is set to /usr/local/apache-kylin-2.5.0-bin-hbase1x
+......
 A new Kylin instance is started by root. To stop it, run 'kylin.sh stop'
-Check the log at /usr/local/apache-kylin-2.3.1-bin/logs/kylin.log
+Check the log at /usr/local/apache-kylin-2.5.0-bin-hbase1x/logs/kylin.log
 Web UI is at http://<hostname>:7070/kylin
--bash-4.1#
-{% endhighlight %}
- * Kylin 启动后您可以通过浏览器 <http://hostname:7070/kylin> 查看。初始用户名和密码是 ADMIN/KYLIN。
- * 运行 `$KYLIN_HOME/bin/kylin.sh stop` 脚本，停止 Kylin。
-{% highlight Groff markup %}
--bash-4.1# $KYLIN_HOME/bin/kylin.sh stop
-Retrieving hadoop conf dir... 
-KYLIN_HOME is set to /usr/local/apache-kylin-2.3.1-bin
-Stopping Kylin: 7014
-Kylin with pid 7014 has been stopped.
-{% endhighlight %}
+```
+
+
+### 使用 Kylin
+
+Kylin 启动后您可以通过浏览器 `http://<hostname>:7070/kylin` 进行访问。
+其中 `<hostname>` 为具体的机器名、IP 地址或域名，默认端口为 7070。
+初始用户名和密码是 `ADMIN/KYLIN`。
+服务器启动后，您可以通过查看 `$KYLIN_HOME/logs/kylin.log` 获得运行时日志。
 
 
+### 停止 Kylin
+
+运行 `$KYLIN_HOME/bin/kylin.sh stop` 脚本来停止 Kylin，界面输出如下：
+
+```
+Retrieving hadoop conf dir...
+KYLIN_HOME is set to /usr/local/apache-kylin-2.5.0-bin-hbase1x
+Stopping Kylin: 25964
+Stopping in progress. Will check after 2 secs again...
+Kylin with pid 25964 has been stopped.
+```
+
+您可以运行 `ps -ef | grep kylin` 来查看 Kylin 进程是否已停止。
\ No newline at end of file


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services