This is an automated email from the ASF dual-hosted git repository.
dockerzhang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/inlong-website.git
The following commit(s) were added to refs/heads/master by this push:
new dfcbc95ec8 [INLONG-659][Doc] Add docs for c++/python sdk. (#660)
dfcbc95ec8 is described below
commit dfcbc95ec855d15157b3f31047979844c9050a3e
Author: Xue Huanran <xuehuan...@163.com>
AuthorDate: Fri Dec 23 15:02:51 2022 +0800
[INLONG-659][Doc] Add docs for c++/python sdk. (#660)
Co-authored-by: huanranxue <huanran...@tencent.com>
Co-authored-by: Charles Zhang <dockerzh...@apache.org>
---
docs/sdk/tubemq-sdk/_category_.json | 4 +
docs/sdk/tubemq-sdk/cpp.md | 144 ++++++++++++++++++++
docs/sdk/tubemq-sdk/python.md | 96 ++++++++++++++
.../current/sdk/tubemq-sdk/cpp.md | 145 +++++++++++++++++++++
.../current/sdk/tubemq-sdk/python.md | 94 +++++++++++++
5 files changed, 483 insertions(+)
diff --git a/docs/sdk/tubemq-sdk/_category_.json
b/docs/sdk/tubemq-sdk/_category_.json
new file mode 100644
index 0000000000..a042e9a5db
--- /dev/null
+++ b/docs/sdk/tubemq-sdk/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "TubeMQ SDK",
+ "position": 3
+ }
\ No newline at end of file
diff --git a/docs/sdk/tubemq-sdk/cpp.md b/docs/sdk/tubemq-sdk/cpp.md
new file mode 100644
index 0000000000..dbba229f0b
--- /dev/null
+++ b/docs/sdk/tubemq-sdk/cpp.md
@@ -0,0 +1,144 @@
+---
+title: C++ SDK
+sidebar_position: 1
+---
+
+## Build TubeMQ C++ SDK
+C++ SDK is based on the non-boost asio, and the CMake is used for building,
the commands are：
+```bash
+# enter the root directory of c++ sdk source
+git clone https://github.com/apache/inlong.git
+cd inlong/inlong-tubemq/tubemq-client-twins/tubemq-client-cpp
+
+mkdir build && cd build
+
+cmake ..
+
+make -j8 # the thread num is based on the cpu cores
+
+```
+
+The building can also be completed in
[docker](https://github.com/apache/inlong/tree/master/inlong-tubemq/tubemq-docker/tubemq-cpp)
environment provided by InLong.
+
+```bash
+# pull image
+docker pull inlong/tubemq-cpp
+
+# start container and mount the source code
+docker run -it --net=host -v ${REPLACE_BY_CPP_SOURCE_DIR_PATH}:/tubemq-cpp/
inlong/tubemq-cpp /bin/bash
+
+# same as the build process in physical machines
+mkdir build && cd build
+cmake ..
+make -j8
+```
+
+## C++ SDK API
+Similar with other MQ systems，C++ SDK is diveded into **Producer** and
**Consumer**. The API of Producer and Consumer are introduced respectively
below.
+
+First of all, regardless of role, start the background global TubeMQ SDK
service (support the default C++ `namespace` is `tubemq`)。
+
+```cpp
+bool StartTubeMQService(string& err_info, const TubeMQServiceConfig&
serviceConfig);
+```
+
+Look up the return boolean value and the `err_info` to check the start process
is successful。
+
+### Producer
+The user-level api class is `TubeMQProducer`，the first thing is initializing
the class.
+
+```cpp
+#include "tubemq/tubemq_client.h" // header file of TubeMQProducer
+
+TubeMQProducer producer;
+```
+
+Set the config of producer, then start the producer
+
+```cpp
+ProducerConfig producer_config;
+producer_config.SetRpcReadTimeoutMs(20000);
+producer_config.SetMasterAddrInfo(err_info, master_addr);
+bool result = producer.start(); // start producer
+```
+
+When `register2Master` is successed，producer will send heartbeat request to
master periodically to update the meta info of topics. Then users can publish
topics, multiple topics can be published at once, and the param type is
`std::set`.
+
+```cpp
+std::set topics{"topic_0", "topic_1"};
+bool result = producer.Publish(err_info, topics);
+```
+
+After publishing, construct the message
+
+```cpp
+#include "tubemq/tubemq_message.h" // header file of tubemq::Message
+
+std::string topic_name = "demo";
+std::string send_data = "hello_world";
+Message message(topic_name, send_data.c_str(), send_data.size()); // type is
const char*
+```
+
+There are two `SendMessage` API: synchronous sending and asynchronous sending.
+
+```cpp
+// sync send
+bool TubeMQProducer::SendMessage(string& err_info, const Message& message);
+// async send
+void TubeMQProducer::SendMessage(const Message& message, const
std::function<void(const ErrorCode&)>& callback);
+```
+
+How to use these two `SendMessage`
+
+```cpp
+bool result = producer.SendMessage(err_info, message);
+
+void callback(const ErrorCode&);
+producer.SendMessage(message, callback); // callback can be other invoked
objects
+```
+
+Synchronous sending will block until the result is returned, asynchronous
sending will not, and the returnted result is received through the user-defined
callback function.
+
+Finally, close the producer.
+
+```cpp
+producer.ShutDown();
+```
+
+### Consumer
+Similar with producer，initialize the consumer object and set the config.
+
+```cpp
+#include "tubemq/tubemq_client.h" // header file of TubeMQConsumer
+
+TubeMQConsumer consumer;
+
+// config of consumption
+ConsumerConfig consumer_config;
+consumer_config.SetRpcReadTimeoutMs(20000);
+consumer_config.SetMasterAddrInfo(err_info, master_addr);
+// set the consume group and the topic
+consumer_config.SetGroupConsumeTarget(err_info, group_name, topic_list);
+
+// start the consumer
+consumer.start();
+```
+
+After starting the consumer, invoke the `GetMessage` to get messages.
+
+```cpp
+ConsumerResult get_result;
+ConsumerResult confirm_result;
+
+bool result = consumer.GetMessage(get_result);
+if (result) {
+ list<Message> messages = get_result.GetMessageList();
+ consumer.Confirm(get_result.GetConfirmContext(), true, confirm_result);
+}
+
+// stop the consumer
+consumer.ShutDown();
+```
+
+### Example
+There are more detailed examples about C++ SDK in [C++ SDK
Example](https://github.com/apache/inlong/tree/master/inlong-tubemq/tubemq-client-twins/tubemq-client-cpp/example)，the
compiled executable is located in `build/example/producer` and
`build/example/consumer`
diff --git a/docs/sdk/tubemq-sdk/python.md b/docs/sdk/tubemq-sdk/python.md
new file mode 100644
index 0000000000..583c3c8c2b
--- /dev/null
+++ b/docs/sdk/tubemq-sdk/python.md
@@ -0,0 +1,96 @@
+---
+title: Python SDK
+sidebar_position: 2
+---
+
+## Build TubeMQ Python SDK
+Python SDK is a wrapper of C++ SDK through
[pybind11](https://pybind11.readthedocs.io/en/stable/), so before building
Python SDK，ensure the C++ SDK has built. The build process of C++ SDK is in
[Build TubeMQ C++ SDK](./cpp.md)
+
+Then install the C++ SDK library and header files.
+
+```bash
+# copy header files
+cp -r /tubemq-cpp/include/tubemq /usr/local/include
+
+# copy third party and tubemq library files
+cp /tubemq-cpp/build/src/libtubemq.a \
+ /tubemq-cpp/build/proto/libtubemq_proto.a \
+ /tubemq-cpp/build/third_party/lib/lib* \
+ /usr/local/lib64/
+
+```
+
+Install `python3`, requirements and python sdk
+
+```bash
+# install requirements
+pip3 install -r requirements.txt
+
+# install python sdk
+python3 setup.py install
+```
+
+After installation，there are compliled so files and python package in
`build/lib`, they can be added to python's `site-packages` or `PYTHONPATH`
+
+## Python SDK API
+Similar with C++ SDK ，Python SDK is also divided into Producer and Consumer.
+
+### Producer
+First of all, initialize `tubemq.Producer`
+
+```python
+import tubemq
+
+master_addr = "127.0.0.1:8000"
+producer = tubemq.Producer(master_addr)
+```
+
+then, publish the topic list
+
+```python
+topic_list = ["topic_0", "topic_1"]
+producer.publish(topic_list)
+```
+
+Construct the `tubemq.Message` and send
+
+```python
+send_data = "hello_tubemq"
+topic_name = "demo"
+msg = tubemq_message.Message(topic_name, send_data, len(send_data))
+if is_sync:
+ result = producer.send(msg, is_sync=True)
+else:
+ producer.send(msg, callback=func) # default is async send
+```
+
+
+The Python SDK also supports synchronous and asynchronous sending methods,
which are similar to C++ SDK. When sending asynchronously, a callable object
should be provided.
+
+
+Finally, stop the producer
+
+```python
+producer.stop()
+```
+
+### Consumer
+Consumer API of Python SDK is similar with Producer, this is a simple example
+
+```python
+import tubemq
+
+master_addr = "127.0.0.1:8000"
+topic_list = ["demo"]
+group_name = "test_group"
+consumer = tubemq.Consumer(master_addr, group_name, topic_list) # initialize
consumer
+
+msgs = consumer.receive()
+if msgs:
+ consumer.acknowledge()
+
+consumer.stop()
+```
+
+### Example
+For more detailed python sdk use cases, please refer to [Python SDK
Example](https://github.com/apache/inlong/tree/master/inlong-tubemq/tubemq-client-twins/tubemq-client-python/src/python/example)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sdk/tubemq-sdk/cpp.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sdk/tubemq-sdk/cpp.md
new file mode 100644
index 0000000000..d7d1019d13
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sdk/tubemq-sdk/cpp.md
@@ -0,0 +1,145 @@
+---
+title: C++ SDK
+sidebar_position: 1
+---
+
+## 构建 TubeMQ C++ SDK
+C++ SDK 主要基于非 Boost 版本的 Asio 进行通信，构建时使用 CMake，具体操作步骤如下：
+```bash
+# 进入到 cpp sdk 的根路径
+git clone https://github.com/apache/inlong.git
+cd inlong/inlong-tubemq/tubemq-client-twins/tubemq-client-cpp
+
+mkdir build && cd build
+
+cmake ..
+
+make -j8 # 可根据自己机器的核数决定编译时使用的线程数量
+
+```
+
+上述构建过程也可以在 InLong
提供的[镜像](https://github.com/apache/inlong/tree/master/inlong-tubemq/tubemq-docker/tubemq-cpp)中完成，具体操作如下
+
+```bash
+# 拉取镜像
+docker pull inlong/tubemq-cpp
+
+# 启动容器，将cpp sdk的源码挂载到容器中
+docker run -it --net=host -v ${REPLACE_BY_CPP_SOURCE_DIR_PATH}:/tubemq-cpp/
inlong/tubemq-cpp /bin/bash
+
+# 之后与在物理机上相同
+mkdir build && cd build
+cmake ..
+make -j8
+```
+
+## C++ SDK API
+与其它的消息队列系统类似，C++ SDK 分为生产者 (Producer) 以及消费者 (Consumer)，下面分别介绍 Producer 和
Consumer 的API使用。
+
+首先，无论是生产者还是消费者，先启动 TubeMQ SDK 的后台全局服务 (以下例子都假定使用的默认 C++ `namespace` 为
`tubemq`)。
+
+```cpp
+bool StartTubeMQService(string& err_info, const TubeMQServiceConfig&
serviceConfig);
+```
+
+通过返回值以及 `err_info` 判断启动是否成功。
+
+### Producer
+对于用户来说，直接接触的类为 `TubeMQProducer`，在使用时需要首先创建实例 。
+
+```cpp
+#include "tubemq/tubemq_client.h" // TubeMQProducer定义头文件
+
+TubeMQProducer producer;
+```
+
+之后设置 `producer` 的配置，并启动。
+
+```cpp
+ProducerConfig producer_config;
+producer_config.SetRpcReadTimeoutMs(20000);
+producer_config.SetMasterAddrInfo(err_info, master_addr);
+bool result = producer.start(); // 启动 producer
+```
+
+当日志显示注册 master 成功后，producer 会以一定频率向 master 发送心跳，以获得最新的关于 topic
的信息，之后用户可以开始订阅想发送消息的 topic，支持订阅多个 topic，传入的 topics 参数类型为 `std::set`。
+
+```cpp
+std::set topics{"topic_0", "topic_1"};
+bool result = producer.Publish(err_info, topics);
+```
+
+订阅之后就可以发送消息，首先对消息进行构造
+
+```cpp
+#include "tubemq/tubemq_message.h" // tubemq::Message 定义头文件
+
+std::string topic_name = "demo";
+std::string send_data = "hello_tubemq";
+Message message(topic_name, send_data.c_str(), send_data.size()); // 接受数据类型为
const char*
+```
+
+构造好消息后，即可发送，SDK 提供了同步和异步两种发送方式
+
+```cpp
+// 同步发送
+bool TubeMQProducer::SendMessage(string& err_info, const Message& message);
+// 异步发送
+void TubeMQProducer::SendMessage(const Message& message, const
std::function<void(const ErrorCode&)>& callback);
+```
+
+分别通过如下方式使用
+
+```cpp
+bool result = producer.SendMessage(err_info, message);
+
+void callback(const ErrorCode&);
+producer.SendMessage(message, callback); // callback 也可以为其它可调用的对象，如 lambda函数
+```
+
+同步发送在得到结果前将会阻塞，异步发送则不会，调用后通过用户自定义的回调函数接收返回的结果。
+
+最后，关闭 producer
+
+```cpp
+producer.ShutDown();
+```
+
+### Consumer
+Consumer 同 Producer 类似，都要先初始化 Consumer 实例，并设置配置，订阅 topic 等操作。
+
+```cpp
+#include "tubemq/tubemq_client.h" // TubeMQConsumer 定义头文件
+
+TubeMQConsumer consumer;
+
+// 消费相关的配置
+ConsumerConfig consumer_config;
+consumer_config.SetRpcReadTimeoutMs(20000);
+consumer_config.SetMasterAddrInfo(err_info, master_addr);
+// consumer中除了订阅 topic，还要设置消费组
+consumer_config.SetGroupConsumeTarget(err_info, group_name, topic_list);
+
+// 启动 consumer
+consumer.start();
+```
+
+启动 consumer 后，调用 `GetMessage` 获取消息即可
+
+```cpp
+ConsumerResult get_result;
+ConsumerResult confirm_result;
+
+bool result = consumer.GetMessage(get_result);
+if (result) {
+ list<Message> messages = get_result.GetMessageList();
+ consumer.Confirm(get_result.GetConfirmContext(), true, confirm_result);
+}
+
+// stop the consumer
+consumer.ShutDown();
+
+```
+
+### Example
+关于 C++ SDK 的更加详细的用例，可以参考 [C++ SDK
Example](https://github.com/apache/inlong/tree/master/inlong-tubemq/tubemq-client-twins/tubemq-client-cpp/example)，编译好的可执行文件位置在
`build/example/producer` 和 `build/example/consumer`。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sdk/tubemq-sdk/python.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sdk/tubemq-sdk/python.md
new file mode 100644
index 0000000000..5b0cf4fc35
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sdk/tubemq-sdk/python.md
@@ -0,0 +1,94 @@
+---
+title: Python SDK
+sidebar_position: 2
+---
+
+## 构建 TubeMQ Python SDK
+Python SDK 主要基于 [pybind11](https://pybind11.readthedocs.io/en/stable/)，对 C++
SDK 进行封装，因此在构建 Python SDK 之前，需要先构建好 C++ SDK，C++ SDK 的构建过程参考 [构建TubeMQ C++
SDK](./cpp.md)
+
+之后将 C++ SDK 的库文件和源文件安装到对应的位置
+
+```bash
+# 拷贝头文件
+cp -r /tubemq-cpp/include/tubemq /usr/local/include
+
+# 拷贝三方依赖，以及libtubemq.a
+cp /tubemq-cpp/build/src/libtubemq.a \
+ /tubemq-cpp/build/proto/libtubemq_proto.a \
+ /tubemq-cpp/build/third_party/lib/lib* \
+ /usr/local/lib64/
+
+```
+
+之后安装 Python3，以及相应的依赖，最后安装 Python SDK
+
+```bash
+# 安装依赖
+pip3 install -r requirements.txt
+
+# 安装 python sdk
+python3 setup.py install
+```
+
+安装后，在 `build/lib` 中可以发现编译好的 so 文件以及 Python 库，直接添加到 Python的 `site-packages`
或者环境变量 `PYTHONPATH` 中均可。
+
+## Python SDK API
+与 C++ SDK 类似，Python SDK 也分为 Producer 和 Consumer 两部分，下面对其进行介绍。
+
+### Producer
+首先初始化 `tubemq.Producer` 实例
+
+```python
+import tubemq
+
+master_addr = "127.0.0.1:8000"
+producer = tubemq.Producer(master_addr)
+```
+
+之后订阅想要发送消息的 topic 列表。
+
+```python
+topic_list = ["topic_0", "topic_1"]
+producer.publish(topic_list)
+```
+
+订阅完成后，直接构造 `tubemq.Message` 并发送消息即可
+
+```python
+send_data = "hello_tubemq"
+topic_name = "demo"
+msg = tubemq_message.Message(topic_name, send_data, len(send_data))
+if is_sync:
+ result = producer.send(msg, is_sync=True)
+else:
+ producer.send(msg, callback=func) # 默认为异步发送
+```
+
+Python SDK 也为同步和异步两种发送方式，和 C++ SDK 的 API 类似，异步发送时，需要提供可调用的对象
+
+最后，停止 producer 即可
+
+```python
+producer.stop()
+```
+
+### Consumer
+Python SDK 的 Consumer API 与 Producer 基本相似，下面为一个简单的例子
+
+```python
+import tubemq
+
+master_addr = "127.0.0.1:8000"
+topic_list = ["demo"]
+group_name = "test_group"
+consumer = tubemq.Consumer(master_addr, group_name, topic_list) # 初始化 consumer
+
+msgs = consumer.receive()
+if msgs:
+ consumer.acknowledge()
+
+consumer.stop()
+```
+
+### Example
+关于 Python SDK 的更加详细的用例，可以参考 [Python SDK
Example](https://github.com/apache/inlong/tree/master/inlong-tubemq/tubemq-client-twins/tubemq-client-python/src/python/example)。
