Skip to content

Commit eacf53a

Browse files
xieyuenxieyuen
authored
docs: 添加 MCDR 插件文档 (#36)
* refactor(config): 更新配置文件类型注解和验证逻辑 - 从 mcdreforged 导入特定类型替代通配符导入 - 为 psi 变量添加 PluginServerInterface 类型注解 - 在属性验证方法中添加浮点数类型断言 - 补充关于布尔值配置项的注释说明 * refactor(kill_server): 重构插件入口点和事件定义 - 将事件定义移至独立的 events.py 文件 - 创建新的 entry.py 作为插件入口点文件 - 从 __init__.py 中移除所有实现代码 - 更新插件版本号至 1.0.1-beta.1 - 添加插件入口点配置 - 优化全局变量引用声明 - 改进 on_info 事件处理器以跳过玩家消息 * fix(kill_server): 修复服务器关闭逻辑并添加插件兼容性检查 - 在服务器已关闭时添加取消强制关闭任务的日志信息 - 移动事件监听器注册代码到条件判断之前避免重复执行 - 添加与 Just Kill It 插件的兼容性检查 - 当检测到冲突插件时自动禁用强制关闭功能并保存配置 - 修复代码结构确保正确的执行流程 * refactor(KillServer): 优化代码结构和改进提示信息 - 将暂停提示文本提取为全局常量 PAUSE_PROMPT 元组 - 移除不必要的全局变量 is_world_saved 声明 - 修复插件兼容性检查方法调用，使用正确的 server.get_plugin_list() - 更新玩家信息判断条件，使用 info.is_user 替代 info.is_player 并添加防熊注释 - 使用 PAUSE_PROMPT 常量替换硬编码的暂停提示字符串匹配 - 改进错误提示信息，明确指出 MC 服务器启动脚本中的 pause 命令问题 * feat(plugin): 增强服务器插件环境检测和生命周期管理 - 添加服务器启动、停止和世界保存事件的日志记录 - 实现服务器停止时的世界保存状态设置逻辑 - 新增环境检查函数验证MCDR处理器兼容性 - 检测并阻止与Just Kill It插件的冲突 - 优化插件加载时的配置验证流程 - 添加对跳转服处理器的不兼容提示 * fix(core): 修复配置禁用时事件监听器重复注册问题 - 在配置禁用时添加返回语句避免后续代码执行 - 防止在 enable=False 情况下仍然注册事件监听器 - 更新插件版本号从 1.0.1-beta.1 到 1.0.1-beta.2 * refactor(events): 重构事件系统并优化事件处理机制 - 将原有独立的事件定义文件整合到统一的 ServerEvents 类中 - 创建 HandlerStorage 管理器统一管理事件处理器的注册和移除 - 使用 ServerEvent 统一处理服务器相关的所有事件类型 - 移除废弃的全局事件调度函数，改用新的事件分发机制 - 优化事件监听器的注册方式，提升代码可维护性 - 整合事件处理逻辑，减少重复代码结构 * refactor(KillServer): 优化代码结构和函数命名 - 重命名 __register_dispatcher 函数为 __reg_dispatcher - 修改内部函数参数名 event 为 e，提高代码简洁性 - 在函数定义间添加空行，改善代码可读性 - 移除多余空行，优化代码布局 - 更新函数调用以匹配新的函数名称 * docs: 添加 MCDR 插件文档站点配置 - 集成 Sphinx 文档构建工具及相关依赖包 - 创建 MCDRpost 插件完整文档页面 - 创建 KillServer 插件完整文档页面 - 添加自定义 Handler API 文档 - 配置文档主题及扩展功能 - 设置多插件文档导航目录 - 添加文档构建脚本和配置文件 * docs(mcdrpost): 更新自定义处理器文档 - 移除 Item 类的 no-index 指令以正确生成文档 * refactor(docs): 优化文档配置中的依赖路径处理 - 添加了 contextlib.suppress 来优雅地处理文件不存在的情况 - 将依赖目录遍历包装在异常抑制块中 - 避免了 FileNotFoundError 导致的构建失败 - 保持了原有的系统路径添加逻辑 - 提高了文档构建过程的健壮性 * docs(MCDRpost): 更新文档样式和内容 - 添加 custom.css 文件支持删除线样式 - 配置 Sphinx 使用自定义 CSS 文件 - 添加删除线角色定义支持文档内删除线语法 - 更新 MCDRpost 文档的标题分隔线格式 - 修复代码块语法使用 code-block 替代 code - 更新 README 中的链接指向 GitHub 仓库文件 - 使用自定义删除线语法替换原来的波浪线删除标记 - 更新各个章节标题的分隔线格式统一化 - 修复 API 文档中对自定义处理器的引用格式 * Squash Merge dev/MCDRpost * update event description * Squash Merge dev/kill_server * docs(kill_server): 更新文档配置并添加事件文档 - 配置 intersphinx 映射链接到 MCDR 官方文档 - 移除无用的注释代码和配置选项 - 新增 events.rst 文件详细记录 KillServer 事件系统 - 在索引中添加事件文档入口 - 简化 readme.rst 中的事件说明，指向新事件文档 * refactor(events): 重构服务器事件定义和分发方式 - 移除全局 server 实例变量，直接使用 PluginServerInterface.psi() 获取实例 - 删除类属性中的事件类型注释，改为直接在常量定义处添加文档字符串 - 为所有事件常量添加详细的中文文档字符串说明 - 更新 dispatch 方法使用 psi() 静态方法替代全局实例调用 - 统一事件常量的命名规范和注释格式 * docs(kill_server): 更新事件文档的引用格式 - 将完整的模块路径引用改为相对引用格式 - 添加了 py:currentmodule 指令简化类引用 - 统一了文档中的类名显示方式 - 修复了文档格式化问题 fix(mcdrpost): 修正文档中的标记格式 - 修正了列表项中的特殊符号格式 - 确保文档渲染的一致性 * docs(kill_server): 修复 GitHub 链接地址 - 将 GitHub 链接从 github/xieyuen/MCDR-Plugins 修正为 github.com/xieyuen/MCDR-Plugins
1 parent d447c30 commit eacf53a

50 files changed

Lines changed: 1957 additions & 674 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/_static/custom.css‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.del {
2+
text-decoration: line-through;
3+
}

‎docs/source/conf.py‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
import datetime
6+
import sys
7+
from pathlib import Path
8+
from contextlib import suppress
9+
10+
# -- Project information -----------------------------------------------------
11+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
12+
13+
project = 'MCDR-Plugins'
14+
copyright = f'{datetime.datetime.now().year}, xieyuen'
15+
author = 'xieyuen'
16+
release = '0.1.0'
17+
18+
src = Path(__file__).parent.parent.parent / "src"
19+
dependencies = Path(__file__).parent.parent.parent / "dependencies"
20+
21+
for directory in src.iterdir():
22+
sys.path.append(str(directory))
23+
24+
with suppress(FileNotFoundError):
25+
for directory in dependencies.iterdir():
26+
sys.path.append(str(directory))
27+
28+
# -- General configuration ---------------------------------------------------
29+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
30+
31+
extensions = [
32+
'sphinx.ext.autodoc',
33+
'sphinx.ext.autosectionlabel',
34+
'sphinx.ext.intersphinx',
35+
'sphinx.ext.napoleon',
36+
'sphinx.ext.viewcode',
37+
'sphinx_copybutton',
38+
'sphinx_prompt',
39+
40+
# For codeblock tabs
41+
# https://github.com/pradyunsg/sphinx-inline-tabs
42+
'sphinx_inline_tabs',
43+
44+
# Mermaid graphs
45+
# https://github.com/mgaitan/sphinxcontrib-mermaid
46+
'sphinxcontrib.mermaid',
47+
48+
# https://sphinx-design.readthedocs.io/en/latest/index.html
49+
# 'sphinx_design',
50+
51+
# https://pypi.org/project/sphinxcontrib.asciinema/
52+
'sphinxcontrib.asciinema'
53+
]
54+
55+
templates_path = ['_templates']
56+
exclude_patterns = []
57+
58+
language = 'zh_CN'
59+
60+
# -- Options for HTML output -------------------------------------------------
61+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
62+
63+
html_theme = 'sphinx_rtd_theme'
64+
html_static_path = ['_static']
65+
html_css_files = ['custom.css']
66+
67+
# -- extension configuations -------------------------------------------------
68+
69+
# 常用的外部文档链接映射
70+
intersphinx_mapping = {
71+
'mcdreforged': ('https://docs.mcdreforged.com/zh-cn/latest/', None),
72+
}
73+
autodoc_default_options = {
74+
'members': True, # 显示所有成员
75+
'member-order': 'bysource', # 按源代码顺序
76+
'special-members': '__init__', # 显示特殊方法
77+
'undoc-members': True, # 显示没有文档的成员
78+
'show-inheritance': True, # 显示继承关系
79+
}
80+
# napoleon_use_ivar = True # 使用 :ivar: 而不是生成独立的属性文档
81+
82+
# 删除线样式
83+
rst_prolog = """
84+
.. role:: del
85+
:class: del
86+
"""

‎docs/source/index.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. MCDR-Plugins documentation master file, created by
2+
sphinx-quickstart on Sat Mar 7 23:53:46 2026.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
MCDR-Plugins 插件文档
7+
==========================
8+
9+
这里是 xieyuen 的 MCDR 插件文档
10+
11+
.. toctree::
12+
:maxdepth: 2
13+
:caption: MCDR Plugins 文档:
14+
15+
MCDRpost<mcdrpost/index.rst>
16+
KillServer<kill_server/index.rst>

‎docs/source/kill_server/events.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
KillServer API -- Events
2+
============================
3+
4+
.. py:currentmodule:: kill_server.events.server_event
5+
6+
KillServer 创建了一些新的事件用以监听服务器的运行状态.
7+
对于 MCDR 内置的一些生命周期事件本插件继续沿用, 并补充了不少
8+
生命周期中的其他事件, 它们都是 :class:`ServerEvent` 的实例
9+
10+
.. autoclass:: ServerEvent
11+
12+
下面是 KillServer 创建的所有事件和 MCDR 服务端控制事件的集合类,
13+
在使用时, 推荐使用此类或直接使用事件 ID
14+
15+
.. autoclass:: ServerEvents

‎docs/source/kill_server/index.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
KillServer 文档
2+
======================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
Readme<readme.rst>
8+
Events<events.rst>

‎docs/source/kill_server/readme.rst‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
KillServer
2+
==========
3+
4+
在关服卡死时强制关闭服务器
5+
6+
.. warning::
7+
此插件使用 `dowhen <http://github.com/gaogaotiantian/dowhen/>`_ 模块实现, 可能不够稳定
8+
9+
.. tip::
10+
BUG Report: `GitHub issues <https://github.com/xieyuen/MCDR-Plugins/issues/new>`_
11+
12+
介绍
13+
----
14+
15+
对于下面的情况(实际可能还有更多适用的情况):
16+
17+
1. Fabric 服务器卡死不关闭
18+
- `MCDReforged/MCDReforged#150 <https://github.com/MCDReforged/MCDReforged/issues/150>`_
19+
- `EngineHub/WorldEdit#2459 <https://github.com/EngineHub/WorldEdit/issues/2459>`_
20+
2. ``pause`` 命令诱发用户Ctrl+C操作，导致 MCDR 关闭与存档恢复冲突，最终致使存档损坏
21+
- `TISUnion/PrimeBackup#85 <https://github.com/TISUnion/PrimeBackup/issues/85>`_
22+
- `MCDReforged/MCDReforged#394 <https://github.com/MCDReforged/MCDReforged/issues/394>`_
23+
24+
本插件提供监听服务器关闭并且在这些情况下强制关闭服务器的功能, 给小白腐竹们提供一个简单且无脑的解决方案
25+
26+
使用方法
27+
--------
28+
29+
直接安装到 MCDR 的插件文件夹下即可, 可以从 `GitHub <https://github.com/xieyuen/MCDR-Plugins>`_
30+
或 `PluginCatalogue <https://mcdreforged.com/zh-CN/plugin/kill_server>`_ 手动下载插件文件
31+
32+
你也可以用下面的 MCDR 命令安装 KillServer
33+
34+
.. code-block::
35+
36+
!!MCDR plg install kill_server
37+
38+
安装后只需要注意服务器关闭不要用 Minecraft 原生的 ``/stop`` 命令, 换用 MCDR 命令来关闭,
39+
比如 ``!!MCDR server stop`` ``!!MCDR server restart``
40+
41+
> 你都用 MCDR 了竟然还不知道原生 ``/stop`` 会让 MCDR 关闭吗?<br>
42+
> 你都用 MCDR 了竟然还用不支持运行时回档的备份模组而不是 PrimeBackup、QuickBackupM 吗?
43+
44+
配置
45+
----
46+
47+
.. list-table::
48+
:widths: 20 15 20 40 15
49+
:header-rows: 1
50+
51+
* - 配置项
52+
- 类型
53+
- 默认值
54+
- 含义
55+
- 注释
56+
* - ``enable``
57+
- ``bool``
58+
- ``True``
59+
- 是否启用插件
60+
- 不影响事件分发
61+
* - ``waiting_time``
62+
- ``float``
63+
- ``60``
64+
- 等待服务器关闭的时间, 超时强制关闭
65+
- 单位为秒
66+
* - ``mcdr_only``
67+
- ``bool``
68+
- ``False``
69+
- 是否只监听 `PluginStoppingServerEvent`
70+
-
71+
72+
新的事件
73+
--------
74+
75+
见 :doc:`events`

0 commit comments

Comments
 (0)