From 8d9485c02e55b32d0ba534522a5b39c5477f7adf Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Sun, 17 Oct 2021 15:37:55 +0800 Subject: [PATCH] update docs --- docs/component/bot/robot-api-12.md | 9 ++++ docs/component/{ => common}/console.md | 0 docs/component/{ => common}/context.md | 2 +- docs/component/{ => common}/coroutine-pool.md | 0 .../{ => common}/global-functions.md | 0 .../component/{ => common}/remote-terminal.md | 0 .../component/{ => common}/singleton-trait.md | 0 docs/component/{ => common}/task-worker.md | 0 docs/component/{ => common}/zmutil.md | 0 docs/component/{ => http}/route-manager.md | 0 docs/component/{ => http}/zmrequest.md | 0 docs/{advanced => faq}/to-v2.md | 0 docs/guide/upgrade.md | 37 ++++++++++++++++ mkdocs.yml | 43 +++++++++++-------- 14 files changed, 71 insertions(+), 20 deletions(-) create mode 100644 docs/component/bot/robot-api-12.md rename docs/component/{ => common}/console.md (100%) rename docs/component/{ => common}/context.md (99%) rename docs/component/{ => common}/coroutine-pool.md (100%) rename docs/component/{ => common}/global-functions.md (100%) rename docs/component/{ => common}/remote-terminal.md (100%) rename docs/component/{ => common}/singleton-trait.md (100%) rename docs/component/{ => common}/task-worker.md (100%) rename docs/component/{ => common}/zmutil.md (100%) rename docs/component/{ => http}/route-manager.md (100%) rename docs/component/{ => http}/zmrequest.md (100%) rename docs/{advanced => faq}/to-v2.md (100%) create mode 100644 docs/guide/upgrade.md diff --git a/docs/component/bot/robot-api-12.md b/docs/component/bot/robot-api-12.md new file mode 100644 index 00000000..ac45f300 --- /dev/null +++ b/docs/component/bot/robot-api-12.md @@ -0,0 +1,9 @@ +# 机器人 API（OneBotV12）（待发布） + +!!! tip "提示" + + 目前由于 OneBot 12 标准还没有定稿，处于草案阶段，故框架暂不更新。 + + 在未来升级到 OneBot 12 标准后，框架会提供转换及兼容措施以及 12 版本的 API 方法。 + +见 [机器人动作（OneBot 11）](../robot-api)。 \ No newline at end of file diff --git a/docs/component/console.md b/docs/component/common/console.md similarity index 100% rename from docs/component/console.md rename to docs/component/common/console.md diff --git a/docs/component/context.md b/docs/component/common/context.md similarity index 99% rename from docs/component/context.md rename to docs/component/common/context.md index 4765b602..65c719bb 100644 --- a/docs/component/context.md +++ b/docs/component/common/context.md @@ -124,7 +124,7 @@ public function ping() { ## getRobot() - 获取机器人 API 对象 -返回当前上下文关联的机器人 API 调用对象 [ZMRobot](bot/robot-api.md)。 +返回当前上下文关联的机器人 API 调用对象 [ZMRobot](../bot/robot-api.md)。 可以使用的事件：所有 HTTP API 发来的事件：`@CQCommand()`，`@CQMessage()` 等。 diff --git a/docs/component/coroutine-pool.md b/docs/component/common/coroutine-pool.md similarity index 100% rename from docs/component/coroutine-pool.md rename to docs/component/common/coroutine-pool.md diff --git a/docs/component/global-functions.md b/docs/component/common/global-functions.md similarity index 100% rename from docs/component/global-functions.md rename to docs/component/common/global-functions.md diff --git a/docs/component/remote-terminal.md b/docs/component/common/remote-terminal.md similarity index 100% rename from docs/component/remote-terminal.md rename to docs/component/common/remote-terminal.md diff --git a/docs/component/singleton-trait.md b/docs/component/common/singleton-trait.md similarity index 100% rename from docs/component/singleton-trait.md rename to docs/component/common/singleton-trait.md diff --git a/docs/component/task-worker.md b/docs/component/common/task-worker.md similarity index 100% rename from docs/component/task-worker.md rename to docs/component/common/task-worker.md diff --git a/docs/component/zmutil.md b/docs/component/common/zmutil.md similarity index 100% rename from docs/component/zmutil.md rename to docs/component/common/zmutil.md diff --git a/docs/component/route-manager.md b/docs/component/http/route-manager.md similarity index 100% rename from docs/component/route-manager.md rename to docs/component/http/route-manager.md diff --git a/docs/component/zmrequest.md b/docs/component/http/zmrequest.md similarity index 100% rename from docs/component/zmrequest.md rename to docs/component/http/zmrequest.md diff --git a/docs/advanced/to-v2.md b/docs/faq/to-v2.md similarity index 100% rename from docs/advanced/to-v2.md rename to docs/faq/to-v2.md diff --git a/docs/guide/upgrade.md b/docs/guide/upgrade.md new file mode 100644 index 00000000..72d1bc81 --- /dev/null +++ b/docs/guide/upgrade.md @@ -0,0 +1,37 @@ +# 升级指南 + +因为框架在随着需求以及 Bug 在不断更新，所以在未来框架会发布新版本。为了方便从旧版本安装并使用框架的开发者无损更新到新版本，这里提供了升级版本上需要注意的事项。 + +## 版本约定 + +炸毛框架的版本号一般情况均按照 [Semantic Versioning 2.0.0](https://semver.org/) 标准进行滚动发行，规则简述如下： + +假设版本号为 x.y.z： + +- `x` 为大版本，一般只有在发生完全无法兼容的更新时增加，需要开发者最重视。 +- `y` 为小发行版本，默认情况下会新增组件功能，但会尽可能兼容旧版本，存在不兼容情况极少。 +- `z` 为补丁版本，在不进行任何大功能更新情况下提供 Bug 的修复，完全兼容前版本。 + +例如，炸毛框架的 `2.4.2` 版本，在 `2.5.0` 发行后，框架提供了大量新组件，但是对旧版本的配置和组件完全兼容，无任何额外的说明，则可以直接升级。 + +## 升级方法 + +根据安装方法不同，升级的方法也不同。 + +框架安装方式有多种，但主要分为三类： + +- Composer 加载库的方式 +- 框架源码模式 +- Phar 打包模式 + +在 Composer 加载库的方式下，一般是指使用命令 `composer require zhamao/framework` 或 `composer create-project zhamao/framework-starter` 的方式安装框架，框架的核心文件都在 `vendor` 目录下。 + +此方式安装的框架升级最方便，直接执行命令 `composer update` 即可。 + +框架源码模式安装一般为直接使用 `git clone` 框架本体的 GitHub 仓库或下载 master 分支安装，这种情况不可升级版本（或使用 `git pull` 拉取）。 + +Phar 打包模式更新则必须重新自行打包新版本，例如从 Composer 加载库方式打包的框架，则需在原目录使用 `composer update` 后再次打包一个新版本。 + +## 升级提示 + +如果在升级过程中遇到了提示，则可能是需要升级某些配置文件需要手动进行合并更新。如果提示了更新，建议到 `vendor/zhamao/framework/config/global.php` 框架的最新库内配置文件与 `config/global.php` 文件进行对比。 \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 34ea5527..6b903763 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,7 @@ theme: accent: indigo features: - navigation.tabs + - navigation.sections extra_javascript: - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js - javascripts/config.js @@ -66,6 +67,7 @@ nav: - 基本配置: guide/basic-config.md - 编写模块: guide/write-module.md - 注册事件响应: guide/register-event.md + - 升级指南: guide/upgrade.md - 错误码对照表: guide/errcode.md - 事件和注解: - 事件和注解: event/index.md @@ -77,9 +79,9 @@ nav: - 事件分发器: event/event-dispatcher.md - 框架组件: - 框架组件: component/index.md - - 上下文: component/context.md - 聊天机器人组件: - - 机器人 API: component/bot/robot-api.md + - 机器人动作（V12）: component/bot/robot-api-12.md + - 机器人动作（V11）: component/bot/robot-api.md - CQ 码（多媒体消息）: component/bot/cqcode.md - 机器人消息处理: component/bot/message-util.md - Token 验证: component/bot/access-token.md @@ -92,33 +94,36 @@ nav: - ZMAtomic 原子计数器: component/store/atomics.md - SpinLock 自旋锁: component/store/spin-lock.md - 文件管理: component/store/data-provider.md + - 通用组件: + - 上下文: component/common/context.md + - 协程池: component/common/coroutine-pool.md + - 单例类: component/common/singleton-trait.md + - ZMUtil 杂项: component/common/zmutil.md + - 全局方法: component/common/global-functions.md + - Console 终端: component/common/console.md + - TaskWorker 管理: component/common/task-worker.md + - Terminal 终端: component/common/remote-terminal.md - HTTP 服务器工具类: - - HTTP 和 WebSocket 客户端: component/zmrequest.md - - HTTP 路由管理: component/route-manager.md + - HTTP 和 WebSocket 客户端: component/http/zmrequest.md + - HTTP 路由管理: component/http/route-manager.md - 模块/插件管理: - 模块打包: component/module/module-pack.md - 模块解包: component/module/module-unpack.md - - 协程池: component/coroutine-pool.md - - 单例类: component/singleton-trait.md - - ZMUtil 杂项: component/zmutil.md - - 全局方法: component/global-functions.md - - Console 终端: component/console.md - - TaskWorker 管理: component/task-worker.md - - Terminal 终端: component/remote-terminal.md - 进阶开发: - 进阶开发: advanced/index.md - - 框架剖析: advanced/framework-structure.md - - 框架启动模式: advanced/custom-start.md - - 手动安装环境: advanced/manually-install.md - - 从 v1 升级: advanced/to-v2.md - - 内部类文件手册: advanced/inside-class.md - - 接入 WebSocket 客户端: advanced/connect-ws-client.md - - 框架多进程: advanced/multi-process.md - - TaskWorker 提高并发: advanced/task-worker.md + - 框架高级开发: + - 框架剖析: advanced/framework-structure.md + - 框架启动模式: advanced/custom-start.md + - 手动安装环境: advanced/manually-install.md + - 内部类文件手册: advanced/inside-class.md + - 框架多进程: advanced/multi-process.md + - TaskWorker 提高并发: advanced/task-worker.md - 开发实战教程: + - 接入 WebSocket 客户端: advanced/connect-ws-client.md - 编写管理员才能触发的功能: advanced/example/admin.md - FAQ: - FAQ: faq/FAQ.md + - 从 v1 升级: faq/to-v2.md - 框架常见问题（持续更新）: faq/usual-question.md - 启动时报错 Address already in use: faq/address-already-in-use.md - 出现 deadlock 字样: faq/display-deadlock.md