Pdf doc (#245)

* update docs

* update docs

* Modify summary for EdgeX Foundry

* Add pre make scripts

* Update docs build command

* update docs

Co-authored-by: wivwiv <bigpar@qq.com>

docs/.gitignore

@@ -1 +1,4 @@
 .lock
+*.pdf
+*.lock
+yarn-error.log

docs/_scripts/make.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+
+const ZH_CN = path.join(__dirname, '../zh_CN')
+const EN_US = path.join(__dirname, '../en_US')
+
+// [[match: regexp | fn | string, replace: regexp fn| string]]
+const replaceRule = [
+  [
+    '[English](README.md) | [简体中文](README-CN.md)',
+    ''
+  ],
+  [
+    '![arch](docs/resources/arch.png)',
+    '![arch](../resources/arch.png)'
+  ],
+  [
+    /]\(docs\/zh_CN\//gim,
+    '](./'
+  ],
+  [
+    /]\(docs\/en_US\//gim,
+    '](./'
+  ],
+  [
+    '(fvt_scripts/edgex/benchmark/pub.go)',
+    'https://github.com/emqx/kuiper/blob/master/fvt_scripts/edgex/pub.go'
+  ],
+  [
+    '[Apache 2.0](LICENSE)',
+    '[Apache 2.0](https://github.com/emqx/kuiper/blob/master/LICENSE)'
+  ]
+]
+
+const readmeMoveRule = [
+  {
+    from: path.join(__dirname, '../../README.md'),
+    to: path.join(EN_US, './README.md'),
+  },
+
+  {
+    from: path.join(__dirname, '../../README-CN.md'),
+    to: path.join(ZH_CN, './README.md'),
+  }
+]
+
+
+function generateReadme() {
+  readmeMoveRule.forEach(fileInfo => {
+    const { from, to } = fileInfo
+    // read
+    let content = fs.readFileSync(from).toString()
+
+    replaceRule.forEach(rule => {
+      content = content.replace(rule[0], rule[1])
+    })
+
+    fs.writeFileSync(
+      to,
+      content,
+    )
+    console.log(`move ${from} to ${to}`)
+  })
+}
+
+generateReadme()

docs/book.json

@@ -1,6 +1,7 @@
 {
   "plugins": [
     "prism",
+    "edit-link",
     "-highlight",
     "-sharing",
     "simple-page-toc",
@@ -8,7 +9,8 @@
     "copy-code-button",
     "anchor-navigation-ex",
     "cuav-chapters",
-    "local-pagefooter"
+    "local-pagefooter",
+    "github-buttons"
   ],
   "structure": {
     "readme": "getting_started.md"
@@ -19,6 +21,19 @@
         "shell": "bash"
       }
     },
+    "edit-link": {
+      "base": "https://github.com/emqx/kuiper/tree/master/docs",
+      "label": "Edit"
+    },
+    "github-buttons": {
+      "buttons": [{
+        "user": "emqx",
+        "repo": "kuiper",
+        "type": "star",
+        "count": true,
+        "size": "small"
+      }]
+    },
     "anchor-navigation-ex": {
       "showLevel": false
     },
@@ -37,8 +52,8 @@
     "epub": "styles/epub.css"
   },
   "title": "Kuiper",
-  "author": "EMQX Team",
-  "language": "zh",
+  "author": "EMQ X Team",
+  "language": "zh-hans",
   "links": {
     "sharing": {
       "facebook": false,

docs/en_US/SUMMARY.md

@@ -1,6 +1,5 @@
-<!-- - [Introduction](README.md) -->
+- [Introduction](./README.md)
 - [Getting started](getting_started.md)
-<!-- ## Reference Guide -->
 - [Reference Guide](reference.md)
 - [Install and operation](operation/overview.md)
   - [Install instruction](operation/install/overview.md)

docs/en_US/book.json

@@ -1,48 +0,0 @@
-{
-  "plugins": [
-    "prism",
-    "-highlight",
-    "-sharing",
-    "simple-page-toc",
-    "anchors",
-    "copy-code-button",
-    "anchor-navigation-ex",
-    "cuav-chapters",
-    "local-pagefooter"
-  ],
-  "structure": {
-    "readme": "getting_started.md"
-  },
-  "pluginsConfig": {
-    "prism": {
-      "lang": {
-        "shell": "bash"
-      }
-    },
-    "anchor-navigation-ex": {
-      "showLevel": false
-    },
-    "local-pagefooter": {
-      "copyright": "© Copyright 2016-2019, EMQ Technologies Co., Ltd.",
-      "islocal": true,
-      "modify_label": "The document reversion time: ",
-      "modify_format": "YYYY-MM-DD HH:mm:ss"
-    }
-  },
-  "styles": {
-    "website": "styles/website.css",
-    "ebook": "styles/ebook.css",
-    "pdf": "styles/pdf.css",
-    "mobi": "styles/mobi.css",
-    "epub": "styles/epub.css"
-  },
-  "title": "Kuiper",
-  "author": "EMQX Team",
-  "language": "zh",
-  "links": {
-    "sharing": {
-      "facebook": false,
-      "twitter": false
-    }
-  }
-}

docs/package.json

@@ -7,12 +7,21 @@
   "license": "Apache 2.0",
   "private": true,
   "scripts": {
-    "serve": "gitbook serve",
-    "docs": "gitbook install && gitbook serve",
-    "html": "gitbook install && gitbook build . _book",
-    "pdf": "gitbook install && gitbook pdf . _book.pdf"
+    "serve": "node _scripts/make && gitbook serve",
+    "docs": "node _scripts/make && gitbook serve",
+    "html": "npm install && node _scripts/make && gitbook build . _book",
+    "pdf": "gitbook pdf . _book.pdf"
   },
   "dependencies": {
-    "gitbook-cli": "^2.3.2"
+    "gitbook-cli": "^2.3.2",
+    "gitbook-plugin-prism": "*",
+    "gitbook-plugin-simple-page-toc": "*",
+    "gitbook-plugin-anchors": "*",
+    "gitbook-plugin-copy-code-button": "*",
+    "gitbook-plugin-anchor-navigation-ex": "*",
+    "gitbook-plugin-cuav-chapters": "*",
+    "gitbook-plugin-local-pagefooter": "*",
+    "gitbook-plugin-edit-link": "*",
+    "gitbook-plugin-github-buttons": "*"
   }
 }

docs/zh_CN/SUMMARY.md

@@ -1,23 +1,23 @@
-<!-- - [Introduction](README.md) -->
-- [快速入门](getting_started.md)
-<!-- ## 参考指南 -->
-- [参考指南](reference.md)
-- [安装与操作](operation/overview.md)
-  - [安装说明](operation/install/overview.md)
-  - [Cent-OS](operation/install/cent-os.md)
-  - [操作指南](operation/operations.md)
-  - [Kuiper 基本配置](operation/configuration_file.md)
-  - [MQTT 源配置](rules/sources/mqtt.md)
-- [命令行界面工具-CLI](cli/overview.md)
+- [概要](./README.md)
+- [安装试用](operation/overview.md)
+  - [下载安装快速入门](getting_started.md) 
+  - [Docker 容器安装教程](quick_start_docker.md) 
+  - [EdgeX Foundry 规则引擎教程](edgex/edgex_rule_engine_tutorial.md)
+- [规则](rules/overview.md) 
+- [命令行工具](cli/overview.md)
   - [流管理](cli/streams.md)
   - [规则管理](cli/rules.md)
+  - [插件管理](cli/plugins.md)
+- [Rest API 接口](restapi/overview.md)
+  - [流管理](restapi/streams.md)
+  - [规则管理](restapi/rules.md)
+  - [插件管理](restapi/plugins.md)
 - [Kuiper SQL 参考](sqls/overview.md)
   - [流规格](sqls/streams.md)
   - [查询语言元素](sqls/query_language_elements.md)
   - [窗口](sqls/windows.md)
   - [函数](sqls/built-in_functions.md)
-- [规则](rules/overview.md)
-  - [日志动作](rules/sinks/logs.md)
-  - [MQTT 动作](rules/sinks/mqtt.md)
 - [扩展 Kuiper](extension/overview.md)
-- [插件](plugins/overview.md)
+- [插件](plugins/overview.md)
+  - [插件开发教程](plugins/plugins_tutorial.md)
+

docs/zh_CN/book.json

@@ -1,48 +0,0 @@
-{
-  "plugins": [
-    "prism",
-    "-highlight",
-    "-sharing",
-    "simple-page-toc",
-    "anchors",
-    "copy-code-button",
-    "anchor-navigation-ex",
-    "cuav-chapters",
-    "local-pagefooter"
-  ],
-  "structure": {
-    "readme": "getting_started.md"
-  },
-  "pluginsConfig": {
-    "prism": {
-      "lang": {
-        "shell": "bash"
-      }
-    },
-    "anchor-navigation-ex": {
-      "showLevel": false
-    },
-    "local-pagefooter": {
-      "copyright": "© Copyright 2016-2019, EMQ Technologies Co., Ltd.",
-      "islocal": true,
-      "modify_label": "The document reversion time: ",
-      "modify_format": "YYYY-MM-DD HH:mm:ss"
-    }
-  },
-  "styles": {
-    "website": "styles/website.css",
-    "ebook": "styles/ebook.css",
-    "pdf": "styles/pdf.css",
-    "mobi": "styles/mobi.css",
-    "epub": "styles/epub.css"
-  },
-  "title": "Kuiper",
-  "author": "EMQX Team",
-  "language": "zh",
-  "links": {
-    "sharing": {
-      "facebook": false,
-      "twitter": false
-    }
-  }
-}

docs/zh_CN/cli/plugins.md

@@ -0,0 +1,94 @@
+# Plugins management
+
+The Kuiper plugin command line tools allows you to manage plugins, such as create, show and drop plugins. Notice that, drop a plugin will need to restart kuiper to take effect. To update a plugin, do the following:
+1. Drop the plugin.
+2. Restart Kuiper.
+3. Create the plugin with the new configuration.
+
+## create a plugin
+
+The command is used for creating a plugin.  The plugin's definition is specified with JSON format.
+
+```shell
+create plugin $plugin_type $plugin_name $plugin_json | create plugin $plugin_type $plugin_name -f $plugin_def_file
+```
+
+The plugin can be created with two ways. 
+
+- Specify the plugin definition in command line.
+
+Sample:
+
+```shell
+# bin/cli create plugin source random {"file":"http://127.0.0.1/plugins/sources/random.zip"}
+```
+
+The command create a source plugin named ``random``. 
+
+- Specify the plugin definition in a file. If the plugin is complex, or the plugin is already wrote in text files with well organized formats, you can just specify the plugin definition through ``-f`` option.
+
+Sample:
+
+```shell
+# bin/cli create plugin sink plugin1 -f /tmp/plugin1.txt
+```
+
+Below is the contents of ``plugin1.txt``.
+
+```json
+{
+  "file":"http://127.0.0.1/plugins/sources/random.zip"
+}
+```
+### parameters
+1. plugin_type: the type of the plugin. Available values are `["source", "sink", "functions"]`
+2. plugin_name: a unique name of the plugin. The name must be the same as the camel case version of the plugin with lowercase first letter. For example, if the exported plugin name is `Random`, then the name of this plugin is `random`.
+3. file: the url of the plugin files. It must be a zip file with: a compiled so file and the yaml file(only required for sources). The name of the files must match the name of the plugin. Please check [Extension](../extension/overview.md) for the naming rule.
+
+## show plugins
+
+The command is used for displaying all plugins defined in the server for a plugin type.
+
+```shell
+show plugins function
+```
+
+Sample:
+
+```shell
+# bin/cli show plugins function
+function1
+function2
+```
+
+## describe a plugin
+The command is used to print out the detailed definition of a plugin.
+
+```shell
+describe plugin $plugin_type $plugin_name
+```
+
+Sample: 
+
+```shell
+# bin/cli describe plugin source plugin1
+{
+  "name": "plugin1",
+  "version": "1.0.0"
+}
+```
+
+## drop a plugin
+
+The command is used for drop the plugin.
+
+```shell
+drop plugin $plugin_type $plugin_name -s $stop 
+```
+In which, `-s $stop` is an optional boolean parameter. If it is set to true, the Kuiper server will be stopped for the delete to take effect. The user will need to restart it manually.
+Sample:
+
+```shell
+# bin/cli drop plugin source random
+Plugin random is dropped.
+```

docs/zh_CN/restapi/overview.md

@@ -0,0 +1,8 @@
+Kuiper provides a set of REST API for streams and rules management in addition to CLI. 
+
+By default, the REST API are running in port 9081. You can change the port in `/etc/kuiper.yaml` for the `restPort` property.
+
+- [Streams](streams.md)
+- [Rules](rules.md)
+- [Plugins](plugins.md)
+

docs/zh_CN/restapi/plugins.md

@@ -0,0 +1,80 @@
+# Plugins management
+
+The Kuiper REST api for plugins allows you to manage plugins, such as create, drop and list plugins. Notice that, drop a plugin will need to restart kuiper to take effect. To update a plugin, do the following:
+1. Drop the plugin.
+2. Restart Kuiper.
+3. Create the plugin with the new configuration.
+
+## create a plugin
+
+The API accepts a JSON content to create a new plugin. Each plugin type has a standalone endpoint. The supported types are `["sources", "sinks", "functions"]`. The plugin is identified by the name. The name must be unique.
+```shell
+POST http://localhost:9081/plugins/sources
+POST http://localhost:9081/plugins/sinks
+POST http://localhost:9081/plugins/functions
+```
+Request Sample
+
+```json
+{
+  "name":"random",
+  "file":"http://127.0.0.1/plugins/sources/random.zip"
+}
+```
+
+### Parameters
+
+1. name: a unique name of the plugin. The name must be the same as the camel case version of the plugin with lowercase first letter. For example, if the exported plugin name is `Random`, then the name of this plugin is `random`.
+2. file: the url of the plugin files. It must be a zip file with: a compiled so file and the yaml file(only required for sources). The name of the files must match the name of the plugin. Please check [Extension](../extension/overview.md) for the naming rule.
+
+
+## show plugins
+
+The API is used for displaying all of plugins defined in the server for a plugin type.
+
+```shell
+GET http://localhost:9081/plugins/sources
+GET http://localhost:9081/plugins/sinks
+GET http://localhost:9081/plugins/functions
+```
+
+Response Sample:
+
+```json
+["plugin1","plugin2"]
+```
+
+## describe a plugin
+
+The API is used to print out the detailed definition of a plugin.
+
+```shell
+GET http://localhost:9081/plugins/sources/{name}
+GET http://localhost:9081/plugins/sinks/{name}
+GET http://localhost:9081/plugins/functions/{name}
+```
+
+Path parameter `name` is the name of the plugin.
+
+Response Sample: 
+
+```json
+{
+  "name": "plugin1",
+  "version": "1.0.0"
+}
+```
+
+## drop a plugin
+
+The API is used for drop the plugin. The kuiper server needs to be restarted to take effect.
+
+```shell
+DELETE http://localhost:8080/plugins/sources/{name}
+DELETE http://localhost:8080/plugins/sinks/{name}
+DELETE http://localhost:8080/plugins/functions/{name}
+```
+The user can pass a query parameter to decide if Kuiper should be stopped after a delete in order to make the deletion take effect. The parameter is `restart` and only when the value is `1` will the Kuiper be stopped. The user has to manually restart it.
+```shell
+DELETE http://localhost:8080/plugins/sources/{name}?restart=1
+```

docs/zh_CN/restapi/rules.md

@@ -0,0 +1,139 @@
+# Rules management
+
+The Kuiper REST api for rules allows you to manage rules, such as create, show, drop, describe, start, stop and restart rules. 
+
+## create a rule
+
+The API accepts a JSON content and create and start a rule.
+```shell
+POST http://localhost:9081/rules
+```
+Request Sample
+
+```json
+{
+  "id": "rule1",
+  "sql": "SELECT * FROM demo",
+  "actions": [{
+    "log":  {}
+  }]
+}
+```
+
+
+## show rules
+
+The API is used for displaying all of rules defined in the server with a brief status.
+
+```shell
+GET http://localhost:9081/rules
+```
+
+Response Sample:
+
+```json
+[
+  {
+    "id": "rule1",
+    "status": "Running"
+  },
+  {
+     "id": "rule2",
+     "status": "Stopped: canceled by error."
+  }
+]
+```
+
+## describe a rule
+
+The API is used for print the detailed definition of rule.
+
+```shell
+GET http://localhost:9081/rules/{id}
+```
+
+Path parameter `id` is the id or name of the rule.
+
+Response Sample: 
+
+```json
+{
+  "sql": "SELECT * from demo",
+  "actions": [
+    {
+      "log": {}
+    },
+    {
+      "mqtt": {
+        "server": "tcp://127.0.0.1:1883",
+        "topic": "demoSink"
+      }
+    }
+  ]
+}
+```
+
+## drop a rule
+
+The API is used for drop the rule.
+
+```shell
+DELETE http://localhost:8080/rules/{id}
+```
+
+
+## start a rule
+
+The API is used to start running the rule.
+
+```shell
+POST http://localhost:8080/rules/{id}/start
+```
+
+
+## stop a rule
+
+The API is used to stop running the rule.
+
+```shell
+POST http://localhost:8080/rules/{id}/stop
+```
+
+## restart a rule
+
+The API is used to restart the rule.
+
+```shell
+POST http://localhost:8080/rules/{id}/restart
+```
+
+## get the status of a rule
+
+The command is used to get the status of the rule. If the rule is running, the metrics will be retrieved realtime. The status can be
+- $metrics
+- stopped: $reason
+
+```shell
+GET http://localhost:8080/rules/{id}/status
+```
+
+Response Sample:
+
+```shell
+{
+    "source_demo_0_records_in_total":5,
+    "source_demo_0_records_out_total":5,
+    "source_demo_0_exceptions_total":0,
+    "source_demo_0_process_latency_ms":0,
+    "source_demo_0_buffer_length":0,
+    "source_demo_0_last_invocation":"2020-01-02T11:28:33.054821",
+    ... 
+    "op_filter_0_records_in_total":5,
+    "op_filter_0_records_out_total":2,
+    "op_filter_0_exceptions_total":0,
+    "op_filter_0_process_latency_ms":0,
+    "op_filter_0_buffer_length":0,
+    "op_filter_0_last_invocation":"2020-01-02T11:28:33.054821",
+    ...
+}
+```

docs/zh_CN/restapi/streams.md

@@ -0,0 +1,74 @@
+# Streams management
+
+The Kuiper REST api for streams allows you to manage the streams, such as create, describe, show and drop stream definitions.
+
+## create a stream
+
+The API is used for creating a stream. For more detailed information of stream definition, please refer to [streams](../sqls/streams.md).
+
+```shell
+POST http://localhost:9081/streams
+```
+Request sample, the request is a json string with `sql` field.
+
+```json
+{"sql":"create stream my_stream (id bigint, name string, score float) WITH ( datasource = \"topic/temperature\", FORMAT = \"json\", KEY = \"id\")"}
+```
+
+This API can run any stream sql statements, not only stream creation.
+
+## show streams
+
+The API is used for displaying all of streams defined in the server.
+
+```shell
+GET http://localhost:9081/streams
+```
+
+Response Sample:
+
+```json
+["mystream"]
+```
+
+## describe a stream
+
+The API is used for print the detailed definition of stream.
+
+```shell
+GET http://localhost:9081/streams/{id}}
+```
+
+Response Sample:
+
+```shell
+{
+  "Name": "demo",
+  "StreamFields": [
+    {
+      "Name": "temperature",
+      "FieldType": {
+        "Type": 2
+      }
+    },
+    {
+      "Name": "ts",
+      "FieldType": {
+        "Type": 1
+      }
+    }
+  ],
+  "Options": {
+    "DATASOURCE": "demo",
+    "FORMAT": "JSON"
+  }
+}
+```
+
+## drop a stream
+
+The API is used for drop the stream definition.
+
+```shell
+DELETE http://localhost:9081/streams/{id}
+```