Skip to content

Commit 9ad350a

Browse files
authored
Merge pull request #1 from ExpTechTW/cdps
Cdps
2 parents 76e4bb2 + d14a105 commit 9ad350a

File tree

31 files changed

+823
-6
lines changed

31 files changed

+823
-6
lines changed

docs/cdps/command/index.mdx

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# 指令
6+
- CDPS 提供簡易的 CLI 工具 執行對應操作
7+
:::note
8+
- 下方指令 在 Source Code 下,需將 `cdps` 替換成 `python main.py`
9+
:::
10+
11+
## 查看 CDPS 的幫助訊息
12+
- `-h` `--help`
13+
```bash
14+
cdps -h
15+
```
16+
:::note
17+
- 可以查看 子指令 幫助訊息
18+
- 範例 `cdps pack -h`
19+
:::
20+
21+
## 查看 CDPS 版本
22+
- `-v` `--version`
23+
```bash
24+
cdps -v
25+
```
26+
27+
## 初始化 CDPS
28+
```bash
29+
cdps init
30+
```
31+
32+
## 啟動 CDPS
33+
- `不帶參數` `start`
34+
```bash
35+
cdps start
36+
```
37+
38+
## 重新生成默認配置 (config.yml)
39+
```bash
40+
cdps gendefault
41+
```
42+
43+
## 打包
44+
```bash
45+
cdps pack --name {資料夾名稱}
46+
```
47+
48+
## 熱載入(Hot reload)
49+
```bash
50+
cdps plugin reload {plugin名稱}
51+
```

docs/cdps/config/index.mdx

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# 配置
6+
- 自定義你的 CDPS 伺服器
7+
8+
## 配置檔
9+
- `./config.yml`
10+
```yml
11+
version: 1 # config 版本號
12+
13+
# "DEBUG" , "INFO" , "WARN" or "ERROR"
14+
log_level: "DEBUG" # 日誌紀錄等級
15+
16+
log_save_days: 7 # 日誌保留天數
17+
```

docs/cdps/develop/index.mdx

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
sidebar_position: 6
3+
---
4+
5+
# 開發
6+
- 這是關於開發 `CDPS` 的文件,如果是要開發擴充 [點擊這裡](../plugin/index.mdx)
7+
:::note
8+
- 如果是一般用戶,可以略過這裡(快跑!!!)
9+
:::
10+
11+
12+
## 從原始碼啟動
13+
- clone 原始碼
14+
- 在根目錄中使用 `python main.py` 啟動 CDPS
15+
16+
## 貢獻
17+
- 至 GitHub 提交 [PR](https://github.com/ExpTechTW/CDPS/pulls)
18+
:::tip
19+
- 開發時應保持 `簡潔` 的原則。
20+
- 若非所有用戶所需之功能,可以參考利用 [Inject 注入](../more/inject.mdx) 的方式實現。
21+
:::

docs/cdps/intro.md

-1
This file was deleted.

docs/cdps/more/dependencies.mdx

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
sidebar_position: 8
3+
---
4+
5+
# 依賴關係
6+
- 擴充 之間的 依賴關係
7+
:::note
8+
- 這是說明 CDPS 擴充之間的依賴關係,如果要找 PyPI依賴 [點擊這裡](./pip.mdx)
9+
:::
10+
11+
## 聲明依賴
12+
-`cdps.json` 中 聲明
13+
:::tip
14+
- 依賴中 `cdps` 為必須的。
15+
:::
16+
```json
17+
{
18+
// ...
19+
"dependencies": {
20+
"cdps": ">=1.0.18" // 擴充所需的 CDPS 最低版本
21+
},
22+
// ...
23+
}
24+
```
25+
26+
## 用途
27+
- 檢查是否有執行擴充所需的其他擴充
28+
:::tip
29+
- 舉例 `cdps_discord` 需要 `cdps_report` 來提供 地震報告 資料。
30+
- 上述例子 `cdps_report` 就是 `cdps_discord` 所需的依賴。
31+
:::

docs/cdps/more/events.mdx

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# 事件列表
6+
- 查看可用的事件
7+
8+
## 目錄
9+
- onServerStartEvent
10+
- onServerCloseEvent
11+
- onCommandEvent
12+
13+
## onServerStartEvent
14+
#### 回傳參數 `pid`
15+
- 當伺服器被啟動
16+
17+
## onServerCloseEvent
18+
#### 回傳參數 `reason(關閉原因)`
19+
- 當伺服器被關閉
20+
21+
## onCommandEvent
22+
#### 回傳參數 `command(用戶輸入內容)`
23+
- 當用戶輸入指令到 terminal

docs/cdps/more/focus-load.mdx

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
sidebar_position: 5
3+
---
4+
5+
# 完全載入
6+
- 等待擴充完全載入後,再繼續下一步動作(載入其他擴充)
7+
8+
:::danger
9+
- 這個選項通常不需要使用。
10+
- 如果不清楚此選項用意,不要輕易使用。
11+
:::
12+
13+
## 用法
14+
-`cdps.json` 中 聲明
15+
```json
16+
{
17+
"version": "1.0.0",
18+
"focus-load": true, // 新增這行
19+
// ...
20+
}
21+
```

docs/cdps/more/index.mdx

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
sidebar_position: 7
3+
---
4+
5+
# 雜項
6+
- 這裡紀錄著,一些瑣碎的東西
7+
8+
## 目錄
9+
- [事件列表](./events.mdx)
10+
- [目錄樹](./tree.mdx)
11+
- [多執行緒(threading)](./thread.mdx)
12+
- [Inject 注入](./inject.mdx)
13+
- [完全載入](./focus-load.mdx)
14+
- [優先載入](./pre-load.mdx)
15+
- [版本管理](./version.mdx)
16+
- [依賴關係](./dependencies.mdx)
17+
- [PyPI 依賴](./pip.mdx)
18+
- [日誌紀錄](./log.mdx)
19+
- [導入 擴充 的 函數](./plugin.mdx)

docs/cdps/more/inject.mdx

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
# Inject 注入
6+
- Server 啟動時會 觸發 `onServerStartEvent`
7+
- 如果我的 擴充 想在 `onServerStartEvent` 前做些什麼 ( 通常是自製的 `日誌擴充` 等 需要在其他擴充前 初始化完成 )
8+
- 這時 `Inject 注入` 就登場了
9+
- 注入新的 `onServerStartEventForExample` 讓其在 `onServerStartEvent` 前 先被執行
10+
:::danger
11+
- 應謹慎使用 `Inject 注入` ,因其會破壞原生方法。
12+
- 使用 `Inject 注入` 的擴充,應在 README 中註明,提醒使用者。
13+
:::
14+
:::note
15+
- 使用了 `Inject 注入` 的案例 [`color_log`](https://github.com/ExpTechTW/CDPS-color_log)
16+
:::
17+
18+
## 原始 類(class)、方法(function)
19+
- `cdps/plugin/events.py`
20+
```py
21+
class onServerStartEvent(Event):
22+
""" 當 伺服器 啟動 """
23+
24+
def __init__(self, pid):
25+
self.pid = pid
26+
```
27+
- `cdps/cdps_server.py`
28+
```py
29+
def on_start(self):
30+
self.event_manager.call_event(onServerStartEvent("start"))
31+
```
32+
## 定義新的類
33+
```py
34+
from cdps.plugin.events import Event
35+
36+
class onServerStartEventForExample(Event):
37+
""" 當 伺服器 啟動 """
38+
def __init__(self, pid):
39+
self.pid = pid
40+
```
41+
## 保留原始方法
42+
```py
43+
original_on_start = cdps.cdps_server.CDPS.on_start
44+
```
45+
## 定義新方法
46+
```py
47+
def _new_on_start(self):
48+
self.event_manager.call_event(onServerStartEventForExample("example")) # 多了這行
49+
original_on_start(self) # 呼叫原始方法
50+
```
51+
## 注入
52+
```py
53+
cdps.cdps_server.CDPS.on_start = _new_on_start
54+
```
55+
56+
## 完成看起來像這樣
57+
```py
58+
from cdps.plugin.manager import Manager , Listener
59+
from cdps.plugin.events import Event
60+
import cdps.cdps_server
61+
62+
class onServerStartEventForExampleEvent(Event):
63+
""" 當 伺服器 啟動 """
64+
def __init__(self, pid):
65+
self.pid = pid
66+
67+
original_on_start = cdps.cdps_server.CDPS.on_start
68+
69+
def _new_on_start(self):
70+
self.event_manager.call_event(onServerStartEventForExampleEvent("example"))
71+
original_on_start(self)
72+
73+
cdps.cdps_server.CDPS.on_start = _new_on_start
74+
75+
class onServerStartEventForExampleListener(Listener):
76+
event = onServerStartEventForExampleEvent
77+
78+
def on_event(self, event):
79+
print(event.pid)
80+
81+
event_manager = Manager()
82+
event_manager.register_listener(onServerStartEventForExampleListener()) # 別忘了監聽事件
83+
```

docs/cdps/more/log.mdx

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
sidebar_position: 10
3+
---
4+
5+
# 日誌紀錄
6+
- 輸出 日誌 到 控制台 並 紀錄到 文件 中。
7+
8+
## 用法
9+
- 獲取 log 實例
10+
:::tip
11+
- Log 類 為 `單例` ,因此可以重複獲取,無需擔心重複。
12+
:::
13+
```py
14+
from cdps.utils.logger import Log # 導入 Log 類
15+
log = Log() # 獲取 log 實例
16+
log.logger.debug("除錯")
17+
log.logger.info("資訊")
18+
log.logger.warning("警告")
19+
log.logger.error("錯誤")
20+
```

docs/cdps/more/pip.mdx

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
sidebar_position: 9
3+
---
4+
5+
# PyPI 依賴
6+
- 依賴的 PyPI 套件
7+
:::note
8+
- 這是說明 PyPI依賴,如果要找 CDPS 擴充之間的依賴關係 [點擊這裡](./dependencies.mdx)
9+
:::
10+
11+
## 聲明依賴
12+
-`cdps.json` 中 聲明
13+
```json
14+
{
15+
// ...
16+
"pip_dependencies": {
17+
"websocket-client": ">=1.8.0" // 擴充所需的 CDPS 最低版本
18+
},
19+
// ...
20+
}
21+
```
22+
23+
## 用途
24+
-`pip_dependencies` 中 聲明 所需的 PyPI依賴,擴充管理器會檢查是否已安裝對應依賴。
25+
:::tip
26+
- 擴充開發者,應加上此參數,避免使用者初次使用,因缺少依賴而崩潰。
27+
:::

docs/cdps/more/plugin.mdx

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
sidebar_position: 11
3+
---
4+
5+
# 導入 擴充 的 函數
6+
- 導入 特定擴充 中的 函數
7+
:::tip
8+
- 使用絕對路徑,從 `./plugins` 開始計算。
9+
:::
10+
```py
11+
# main.py (report plugin)
12+
from plugins.report.src.events import onReport # 導入自己的 函數
13+
from plugins.discord_webhook import send_webhook # 導入 其他擴充 的 函數
14+
```

docs/cdps/more/pre-load.mdx

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
sidebar_position: 6
3+
---
4+
5+
# 優先載入
6+
- 優先被 擴充管理器 載入
7+
8+
:::caution
9+
- 擴充管理器 會根據 擴充之間的依賴關係,自動調整載入順序。
10+
- 這個選項通常不需要使用。
11+
- 如果不清楚此選項用意,不要輕易使用。
12+
:::
13+
14+
## 用法
15+
-`cdps.json` 中 聲明
16+
```json
17+
{
18+
"version": "1.0.0",
19+
"pre-load": true, // 新增這行
20+
// ...
21+
}
22+
```

0 commit comments

Comments
 (0)