Merge pull request #1 from ExpTechTW/cdps

Cdps

Author: whes1015

docs/cdps/command/index.mdx

@@ -0,0 +1,51 @@
+---
+sidebar_position: 3
+---
+
+# 指令
+- CDPS 提供簡易的 CLI 工具 執行對應操作
+:::note
+- 下方指令 在 Source Code 下，需將 `cdps` 替換成 `python main.py`。
+:::
+
+## 查看 CDPS 的幫助訊息
+- `-h` `--help`
+```bash
+cdps -h
+```
+:::note
+- 可以查看 子指令 幫助訊息
+- 範例 `cdps pack -h`
+:::
+
+## 查看 CDPS 版本
+- `-v` `--version`
+```bash
+cdps -v
+```
+
+## 初始化 CDPS
+```bash
+cdps init
+```
+
+## 啟動 CDPS
+- `不帶參數` `start`
+```bash
+cdps start
+```
+
+## 重新生成默認配置 (config.yml)
+```bash
+cdps gendefault
+```
+
+## 打包
+```bash
+cdps pack --name {資料夾名稱}
+```
+
+## 熱載入(Hot reload)
+```bash
+cdps plugin reload {plugin名稱}
+```

docs/cdps/config/index.mdx

@@ -0,0 +1,17 @@
+---
+sidebar_position: 2
+---
+
+# 配置
+- 自定義你的 CDPS 伺服器
+
+## 配置檔
+- `./config.yml`
+```yml
+version: 1           # config 版本號
+
+# "DEBUG" , "INFO" , "WARN" or "ERROR"
+log_level: "DEBUG"   # 日誌紀錄等級
+
+log_save_days: 7     # 日誌保留天數
+```

docs/cdps/develop/index.mdx

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

docs/cdps/intro.md

@@ -0,0 +1,31 @@
+---
+sidebar_position: 8
+---
+
+# 依賴關係
+- 擴充 之間的 依賴關係
+:::note
+- 這是說明 CDPS 擴充之間的依賴關係，如果要找 PyPI依賴 [點擊這裡](./pip.mdx)
+:::
+
+## 聲明依賴
+- 在 `cdps.json` 中 聲明
+:::tip
+- 依賴中 `cdps` 為必須的。
+:::
+```json
+{
+    // ...
+    "dependencies": {
+        "cdps": ">=1.0.18"                                      // 擴充所需的 CDPS 最低版本
+    },
+    // ...
+}
+```
+
+## 用途
+- 檢查是否有執行擴充所需的其他擴充
+:::tip
+- 舉例 `cdps_discord` 需要 `cdps_report` 來提供 地震報告 資料。
+- 上述例子 `cdps_report` 就是 `cdps_discord` 所需的依賴。
+:::

docs/cdps/more/dependencies.mdx

@@ -0,0 +1,23 @@
+---
+sidebar_position: 1
+---
+
+# 事件列表
+- 查看可用的事件
+
+## 目錄
+- onServerStartEvent
+- onServerCloseEvent
+- onCommandEvent
+
+## onServerStartEvent
+#### 回傳參數 `pid`
+- 當伺服器被啟動
+
+## onServerCloseEvent
+#### 回傳參數 `reason(關閉原因)`
+- 當伺服器被關閉
+
+## onCommandEvent
+#### 回傳參數 `command(用戶輸入內容)`
+- 當用戶輸入指令到 terminal

docs/cdps/more/events.mdx

@@ -0,0 +1,21 @@
+---
+sidebar_position: 5
+---
+
+# 完全載入
+- 等待擴充完全載入後，再繼續下一步動作(載入其他擴充)
+
+:::danger
+- 這個選項通常不需要使用。
+- 如果不清楚此選項用意，不要輕易使用。
+:::
+
+## 用法
+- 在 `cdps.json` 中 聲明
+```json
+{
+    "version": "1.0.0",
+    "focus-load": true,     // 新增這行
+    // ...
+}
+```

docs/cdps/more/focus-load.mdx

@@ -0,0 +1,19 @@
+---
+sidebar_position: 7
+---
+
+# 雜項
+- 這裡紀錄著，一些瑣碎的東西
+
+## 目錄
+- [事件列表](./events.mdx)
+- [目錄樹](./tree.mdx)
+- [多執行緒(threading)](./thread.mdx)
+- [Inject 注入](./inject.mdx)
+- [完全載入](./focus-load.mdx)
+- [優先載入](./pre-load.mdx)
+- [版本管理](./version.mdx)
+- [依賴關係](./dependencies.mdx)
+- [PyPI 依賴](./pip.mdx)
+- [日誌紀錄](./log.mdx)
+- [導入 擴充 的 函數](./plugin.mdx)

docs/cdps/more/index.mdx

@@ -0,0 +1,83 @@
+---
+sidebar_position: 4
+---
+
+# Inject 注入
+- Server 啟動時會 觸發 `onServerStartEvent`
+- 如果我的 擴充 想在 `onServerStartEvent` 前做些什麼 ( 通常是自製的 `日誌擴充` 等 需要在其他擴充前 初始化完成 )
+- 這時 `Inject 注入` 就登場了
+- 注入新的 `onServerStartEventForExample` 讓其在 `onServerStartEvent` 前 先被執行
+:::danger
+- 應謹慎使用 `Inject 注入` ，因其會破壞原生方法。
+- 使用 `Inject 注入` 的擴充，應在 README 中註明，提醒使用者。
+:::
+:::note
+- 使用了 `Inject 注入` 的案例 [`color_log`](https://github.com/ExpTechTW/CDPS-color_log)。
+:::
+
+## 原始 類(class)、方法(function)
+- `cdps/plugin/events.py`
+```py
+class onServerStartEvent(Event):
+    """ 當 伺服器 啟動 """
+
+    def __init__(self, pid):
+        self.pid = pid
+```
+- `cdps/cdps_server.py`
+```py
+def on_start(self):
+    self.event_manager.call_event(onServerStartEvent("start"))
+```
+## 定義新的類
+```py
+from cdps.plugin.events import Event
+
+class onServerStartEventForExample(Event):
+    """ 當 伺服器 啟動 """
+    def __init__(self, pid):
+        self.pid = pid
+```
+## 保留原始方法
+```py
+original_on_start = cdps.cdps_server.CDPS.on_start
+```
+## 定義新方法
+```py
+def _new_on_start(self):
+    self.event_manager.call_event(onServerStartEventForExample("example")) # 多了這行
+    original_on_start(self)                                                # 呼叫原始方法
+```
+## 注入
+```py
+cdps.cdps_server.CDPS.on_start = _new_on_start
+```
+
+## 完成看起來像這樣
+```py
+from cdps.plugin.manager import Manager , Listener
+from cdps.plugin.events import Event
+import cdps.cdps_server
+
+class onServerStartEventForExampleEvent(Event):
+    """ 當 伺服器 啟動 """
+    def __init__(self, pid):
+        self.pid = pid
+
+original_on_start = cdps.cdps_server.CDPS.on_start
+
+def _new_on_start(self):
+    self.event_manager.call_event(onServerStartEventForExampleEvent("example"))
+    original_on_start(self)
+
+cdps.cdps_server.CDPS.on_start = _new_on_start
+
+class onServerStartEventForExampleListener(Listener):
+    event = onServerStartEventForExampleEvent
+
+    def on_event(self, event):
+        print(event.pid)
+
+event_manager = Manager()
+event_manager.register_listener(onServerStartEventForExampleListener())    # 別忘了監聽事件
+```

docs/cdps/more/inject.mdx

@@ -0,0 +1,20 @@
+---
+sidebar_position: 10
+---
+
+# 日誌紀錄
+- 輸出 日誌 到 控制台 並 紀錄到 文件 中。
+
+## 用法
+- 獲取 log 實例
+:::tip
+- Log 類 為 `單例` ，因此可以重複獲取，無需擔心重複。
+:::
+```py
+from cdps.utils.logger import Log   # 導入 Log 類
+log = Log()                         # 獲取 log 實例
+log.logger.debug("除錯")
+log.logger.info("資訊")
+log.logger.warning("警告")
+log.logger.error("錯誤")
+```

docs/cdps/more/log.mdx

@@ -0,0 +1,27 @@
+---
+sidebar_position: 9
+---
+
+# PyPI 依賴
+- 依賴的 PyPI 套件
+:::note
+- 這是說明 PyPI依賴，如果要找 CDPS 擴充之間的依賴關係 [點擊這裡](./dependencies.mdx)。
+:::
+
+## 聲明依賴
+- 在 `cdps.json` 中 聲明
+```json
+{
+    // ...
+    "pip_dependencies": {
+        "websocket-client": ">=1.8.0"                                      // 擴充所需的 CDPS 最低版本
+    },
+    // ...
+}
+```
+
+## 用途
+- 在 `pip_dependencies` 中 聲明 所需的 PyPI依賴，擴充管理器會檢查是否已安裝對應依賴。
+:::tip
+- 擴充開發者，應加上此參數，避免使用者初次使用，因缺少依賴而崩潰。
+:::

docs/cdps/more/pip.mdx

@@ -0,0 +1,14 @@
+---
+sidebar_position: 11
+---
+
+# 導入 擴充 的 函數
+- 導入 特定擴充 中的 函數
+:::tip
+- 使用絕對路徑，從 `./plugins` 開始計算。
+:::
+```py
+# main.py (report plugin)
+from plugins.report.src.events import onReport      # 導入自己的 函數
+from plugins.discord_webhook import send_webhook    # 導入 其他擴充 的 函數
+```

docs/cdps/more/plugin.mdx

@@ -0,0 +1,22 @@
+---
+sidebar_position: 6
+---
+
+# 優先載入
+- 優先被 擴充管理器 載入
+
+:::caution
+- 擴充管理器 會根據 擴充之間的依賴關係，自動調整載入順序。
+- 這個選項通常不需要使用。
+- 如果不清楚此選項用意，不要輕易使用。
+:::
+
+## 用法
+- 在 `cdps.json` 中 聲明
+```json
+{
+    "version": "1.0.0",
+    "pre-load": true,     // 新增這行
+    // ...
+}
+```