Merge branch 'master' of github.com:wechaty/python-wechaty

Author: wj-Mcat

docs/explanation/different_protocol.md

@@ -1,2 +1,28 @@
-# 各种协议
->这里应该是介绍各种协议存在的原因，通信原理等。以及可以分析一下不同协议使用的利弊等等。
+## 一、支持的协议
+
+一个Wechaty实例/派生类就是机器人对象，能够根据`TOKEN`找到连接的服务，获取用户自模块执行搜索，而这些信息都是由Wechaty实例管理。
+
+> 由于服务的连接信息是保存到实例当中，故用户子模块一定要通过Wechaty实例来获取。例如：bot.Contact.find_all()
+
+### 1.1 什么是协议
+
+所有实现底层平台对接实现就是一个协议。
+
+python-wechaty理论上能够对接所有IM平台，目前已经对接微信、微信公众号、钉钉、飞书以及WhatsApp等平台，源码都是基于TypeScript语言，可是通过`wechaty-puppet-service`能够将其服务以gRPC的形式暴露出来，提供给多语言`Wechaty`来连接。例如微信免费Web协议，底层实现是基于TyepScript编写，可是通过社区生态项目，可是都可以使用docker将接口的实现部署成服务。
+
+比如[wechaty-puppet-wechat](https://github.com/wechaty/wechaty-puppet-wechat)能够通过[wechaty/wechaty:latest](https://hub.docker.com/r/wechaty/wechaty)镜像将其所有实现接口暴露成gRPC的服务，非常的方便，已然实现`write once, run anywhere`。
+
+### 1.2 协议列表
+
+目前python-wechaty能够使用wechaty生态中所有IM平台对接协议，协议列表如下所示：
+
+* [wechaty-puppet-wechaty](https://github.com/wechaty/wechaty-puppet-wechat): 免费微信Web协议
+* [wechaty-puppet-](https://github.com/wechaty/wechaty-puppet-macOS): 免费微信MacOs协议
+* [wechaty-puppet-padlocal](https://github.com/wechaty/wechaty-puppet-padlocal): 付费微信Pad协议
+* [wechaty-puppet-official-account](https://github.com/wechaty/wechaty-puppet-official-account): 微信公众号协议
+* [wechaty-puppet-lark](https://github.com/wechaty/wechaty-puppet-lark): 飞书协议
+* [wechaty-puppet-dingtalk](https://github.com/wechaty/wechaty-puppet-dingtalk): 钉钉协议
+* [wechaty-puppet-teams](https://github.com/wechaty/wechaty-puppet-dingtalk): 微软Teams协议
+* ......
+
+

docs/references/friendship.md

@@ -2,38 +2,23 @@
 title: Friendship
 ---
 
-发送、接收好友请求和好友确认事件。
+# class Friendship()
+> 发送、接收好友请求和好友确认事件。
+> [示例/Friend-Bot](https://github.com/wechaty/python-wechaty-getting-started/blob/master/examples/advanced/friendship-bot.py)
 
-## Friendship
 
-发送、接收好友请求和好友确认事件。
+::: wechaty.user.friendship.Friendship.search
 
-1. 发送请求
-2. 接收请求\(in friend event\)
-3. 接受请求\(friend event\)
-
-[示例/Friend-Bot](https://github.com/wechaty/python-wechaty-getting-started/blob/master/examples/advanced/friendship-bot.py)
-
-**类型**: 全局类
-
-* [Friendship](friendship.md#Friendship)
-  * _实例方法_
-    * [.accept\(\)](friendship.md#Friendship+accept) ⇒ `None`
-    * [.hello\(\)](friendship.md#Friendship+hello) ⇒ `str`
-    * [.contact\(\)](friendship.md#Friendship+contact) ⇒ `Contact`
-    * [.type\(\)](friendship.md#Friendship+type) ⇒ `FriendshipType`
-  * _静态方法_
-    * [~~.send\(\)~~](friendship.md#Friendship.send)
-    * [.add\(contact, hello\)](friendship.md#Friendship.add) ⇒ `None`
-
-### friendship.accept\(\) ⇒ `None`
-
-接受朋友请求
-
-**类型**: [`Friendship`](friendship.md#Friendship)的实例方法  
-
-#### 示例
+::: wechaty.user.friendship.Friendship.add
+### 示例代码
+```python
+memberList = await room.memberList()
+for member in memberList:
+    await bot.Friendship.add(member, 'Nice to meet you! I am wechaty bot!')
+```
 
+::: wechaty.user.friendship.Friendship.contact
+### 示例代码
 ```python
 import asyncio
 from wechaty import Wechaty, Friendship
@@ -44,97 +29,45 @@ class MyBot(Wechaty):
     async on_friendship(self, friendship: Friendship) -> None:
         contact = friendship.contact()
         await contact.ready()
-
-        if friendship.type() == FriendshipType.FRIENDSHIP_TYPE_RECEIVE:
-            log_msg = 'accepted automatically'
-            await friendship.accept()
-            # if want to send msg, you need to delay sometimes
-
-            print('waiting to send message ...')
-            await asyncio.sleep(3)
-            await contact.say('hello from wechaty ...')
-            print('after accept ...')
-        elif friendship.type() == FriendshipType.FRIENDSHIP_TYPE_CONFIRM:
-            log_msg = 'friend ship confirmed with ' + contact.name
-
+        log_msg = f'receive "friendship" message from {contact.name}'
         print(log_msg)
 
+
 asyncio.run(MyBot().start())
 ```
 
-### friendship.hello\(\) ⇒ `str`
-
-Get verify message from
-
-**类型**: [`Friendship`](friendship.md#Friendship)的实例方法  
-
-**示例** 
-
-_\(If request content is \`ding\`, then accept the friendship\)_
-
+::: wechaty.user.friendship.Friendship.accept
+### 示例代码
 ```python
 import asyncio
 from wechaty import Wechaty, Friendship
 
-
 class MyBot(Wechaty):
 
     async on_friendship(self, friendship: Friendship) -> None:
         contact = friendship.contact()
         await contact.ready()
 
-        if friendship.type() == FriendshipType.FRIENDSHIP_TYPE_RECEIVE and friendship.hello() == 'ding':
-            log_msg = 'accepted automatically because verify messsage is "ding"'
+        if friendship.type() == FriendshipType.FRIENDSHIP_TYPE_RECEIVE:
+            log_msg = 'accepted automatically'
             await friendship.accept()
             # if want to send msg, you need to delay sometimes
 
             print('waiting to send message ...')
             await asyncio.sleep(3)
             await contact.say('hello from wechaty ...')
             print('after accept ...')
+        elif friendship.type() == FriendshipType.FRIENDSHIP_TYPE_CONFIRM:
+            log_msg = 'friend ship confirmed with ' + contact.name
 
-asyncio.run(MyBot().start())
-```
-
-### friendship.contact\(\) ⇒ `Contact`
-
-获取邀请的联系人对象
-
-**类型**: [`Friendship`](friendship.md#Friendship)的实例方法  
-
-#### 示例
-
-```python
-import asyncio
-from wechaty import Wechaty, Friendship
-
-
-class MyBot(Wechaty):
-
-    async on_friendship(self, friendship: Friendship) -> None:
-        contact = friendship.contact()
-        await contact.ready()
-        log_msg = f'receive "friendship" message from {contact.name}'
         print(log_msg)
 
-
 asyncio.run(MyBot().start())
 ```
 
-### friendship.type\(\) ⇒ `FriendshipType`
-
-返回Friendship请求的类型
-
-> 提示: FriendshipType在这里是枚举类型. </br>
->
-> * FriendshipType.FriendshipTypeFRIENDSHIP_TYPE_UNSPECIFIED
-> * FriendshipType.FRIENDSHIP_TYPE_CONFIRM 
-> * FriendshipType.FRIENDSHIP_TYPE_RECEIVE 
-> * FriendshipType.FRIENDSHIP_TYPE_VERIFY 
-
-**类型**: [`Friendship`](friendship.md#Friendship)的实例方法  
-
-**示例** _\(If request content is \`ding\`, then accept the friendship\)_
+::: wechaty.user.friendship.Friendship.hello
+### 示例代码
+> 自动接受好友请求中包含消息为 `ding` 的好友请求
 
 ```python
 import asyncio
@@ -160,32 +93,6 @@ class MyBot(Wechaty):
 asyncio.run(MyBot().start())
 ```
 
-### ~~Friendship.send\(\)~~
-
-_**已弃用**_
-
-请使用[Friendship\#add](friendship.md#friendship-add-contact-hello-promise)
-
-**类型**:  [`Friendship`](friendship.md#Friendship)的静态方法
-
-### Friendship.add\(contact, hello\) ⇒ `Promise <void>`
-
-Send a Friend Request to a `contact` with message `hello`.
-
-The best practice is to send friend request once per minute. Remeber not to do this too frequently, or your account may be blocked.
+::: wechaty.user.friendship.Friendship.type
 
-**类型**:  [`Friendship`](friendship.md#Friendship)的静态方法
-
-| 参数 | 类型 | 描述 |
-| :--- | :--- | :--- |
-| contact | `Contact` | Send friend request to contact |
-| hello | `string` | The friend request content |
-
-#### Example
-
-```python
-memberList = await room.memberList()
-for member in memberList:
-    await bot.Friendship.add(member, 'Nice to meet you! I am wechaty bot!')
-
-```
+::: wechaty.user.friendship.Friendship.from_json