docs: 添加 MCDR 插件文档

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,77 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import datetime
+import sys
+from pathlib import Path
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'MCDR-Plugins'
+copyright = f'{datetime.datetime.now().year}, xieyuen'
+author = 'xieyuen'
+release = '0.1.0'
+
+src = Path(__file__).parent.parent.parent / "src"
+dependencies = Path(__file__).parent.parent.parent / "dependencies"
+
+for directory in src.iterdir():
+    sys.path.append(str(directory))
+for directory in dependencies.iterdir():
+    sys.path.append(str(directory))
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx_copybutton',
+    'sphinx_prompt',
+
+    # For codeblock tabs
+    # https://github.com/pradyunsg/sphinx-inline-tabs
+    'sphinx_inline_tabs',
+
+    # Mermaid graphs
+    # https://github.com/mgaitan/sphinxcontrib-mermaid
+    'sphinxcontrib.mermaid',
+
+    # https://sphinx-design.readthedocs.io/en/latest/index.html
+    # 'sphinx_design',
+
+    # https://pypi.org/project/sphinxcontrib.asciinema/
+    'sphinxcontrib.asciinema'
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+language = 'zh_CN'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# -- extension configuations -------------------------------------------------
+
+# 常用的外部文档链接映射
+# intersphinx_mapping = {
+#     'python': ('https://docs.python.org/3', None),
+#     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+#     'mcdr': ('https://mcdreforged.com', None)
+# }
+autodoc_default_options = {
+    'members': True,           # 显示所有成员
+    'member-order': 'bysource', # 按源代码顺序
+    'special-members': '__init__',  # 显示特殊方法
+    'undoc-members': True,      # 显示没有文档的成员
+    'show-inheritance': True,   # 显示继承关系
+}

docs/source/index.rst

@@ -0,0 +1,16 @@
+.. MCDR-Plugins documentation master file, created by
+   sphinx-quickstart on Sat Mar  7 23:53:46 2026.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+MCDR-Plugins 插件文档
+==========================
+
+这里是 xieyuen 的 MCDR 插件文档
+
+.. toctree::
+   :maxdepth: 2
+   :caption: MCDR Plugins 文档:
+
+   MCDRpost<mcdrpost/index.rst>
+   KillServer<kill_server/index.rst>

docs/source/kill_server/index.rst

@@ -0,0 +1,7 @@
+KillServer 文档
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   Readme<readme.rst>

docs/source/kill_server/readme.rst

@@ -0,0 +1,138 @@
+KillServer
+==========
+
+在关服卡死时强制关闭服务器
+
+.. warning::
+   此插件使用 `dowhen <http://github.com/gaogaotiantian/dowhen/>`_ 模块实现, 可能不够稳定
+
+.. tip::
+   BUG Report: `GitHub issues <https://github.com/xieyuen/MCDR-Plugins/issues/new>`_
+
+介绍
+----
+
+对于下面的情况(实际可能还有更多适用的情况):
+
+1. Fabric 服务器卡死不关闭
+    - `MCDReforged/MCDReforged#150 <https://github.com/MCDReforged/MCDReforged/issues/150>`_
+    - `EngineHub/WorldEdit#2459 <https://github.com/EngineHub/WorldEdit/issues/2459>`_
+2. ``pause`` 命令诱发用户Ctrl+C操作，导致 MCDR 关闭与存档恢复冲突，最终致使存档损坏
+    - `TISUnion/PrimeBackup#85 <https://github.com/TISUnion/PrimeBackup/issues/85>`_
+    - `MCDReforged/MCDReforged#394 <https://github.com/MCDReforged/MCDReforged/issues/394>`_
+
+本插件提供监听服务器关闭并且在这些情况下强制关闭服务器的功能, 给小白腐竹们提供一个简单且无脑的解决方案
+
+使用方法
+--------
+
+直接安装到 MCDR 的插件文件夹下即可, 可以从 `GitHub <https://github/xieyuen/MCDR-Plugins>`_
+或 `PluginCatalogue <https://mcdreforged.com/zh-CN/plugin/kill_server>`_ 手动下载插件文件
+
+你也可以用下面的 MCDR 命令安装 KillServer
+
+.. code:: mcdr
+
+   !!MCDR plg install kill_server
+
+安装后只需要注意服务器关闭不要用 Minecraft 原生的 ``/stop`` 命令, 换用 MCDR 命令来关闭,
+比如 ``!!MCDR server stop`` ``!!MCDR server restart``
+
+> 你都用 MCDR 了竟然还不知道原生 ``/stop`` 会让 MCDR 关闭吗?<br>
+> 你都用 MCDR 了竟然还用不支持运行时回档的备份模组而不是 PrimeBackup、QuickBackupM 吗?
+
+配置
+----
+
+.. list-table::
+   :widths: 20 15 20 40 15
+   :header-rows: 1
+
+   * - 配置项
+     - 类型
+     - 默认值
+     - 含义
+     - 注释
+   * - ``enable``
+     - ``bool``
+     - ``True``
+     - 是否启用插件
+     - 不影响事件分发
+   * - ``waiting_time``
+     - ``float``
+     - ``60``
+     - 等待服务器关闭的时间, 超时强制关闭
+     - 单位为秒
+   * - ``mcdr_only``
+     - ``bool``
+     - ``False``
+     - 是否只监听 `PluginStoppingServerEvent`_
+     -
+
+新的事件
+--------
+
+KillServer 创建了三个字面量事件 `ServerStoppingEvent`_,
+`PluginStoppingServerEvent`_
+和 `WorldSavedEvent`_ 用以监听服务器控制事件
+
+你可以通过下面的方式在自己的插件中使用这些事件
+
+.. code:: python
+
+    from kill_server import ServerStoppingEvent, PluginStoppingServerEvent, WorldSavedEvent
+    from mcdreforged import event_listener, PluginServerInterface
+
+
+    # import
+    @event_listener(ServerStoppingEvent)
+    def on_server_stopping(server: PluginServerInterface):
+        pass
+
+
+    # or id
+    @event_listener("kill_server.server_stopping")  # also
+    def on_server_stopping(server: PluginServerInterface):
+        pass
+
+.. tip::
+   如果你只是需要各个事件而不需要强制关闭功能的话可以把配置中的 ``enable`` 项设定为 ``false``,
+   该配置只会影响强制关闭功能而不会停止事件分发
+
+.. _ServerStoppingEvent:
+
+ServerStoppingEvent
+^^^^^^^^^^^^^^^^^^^
+
+字面量事件 ``ServerStoppingEvent = LiteralEvent("kill_server.server_stopping")``
+用以监听服务器关闭, 这个事件会在服务器开始关闭时 (例如 ``/stop`` 被调用时) 触发
+
+- **事件 ID**: ``kill_server.server_stopping``
+- **回调参数**: ``PluginServerInterface``
+
+.. _PluginStoppingServerEvent:
+
+PluginStoppingServerEvent
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+事件 ``PluginStoppingServerEvent = LiteralEvent("kill_server.plugin_stopping_server")``
+用以监听 ***由插件调用 ``ServerInterface.stop()`` 或调用 MCDR 命令*** 导致的服务器开始关闭,
+这个事件会在服务器关闭时 (例如 ``!!MCDR server stop`` 被调用时) 触发
+
+.. important::
+   1. 该事件同时会引发 `ServerStoppingEvent`_
+   2. ``ServerInterface.kill()`` 不会触发该事件, 因为服务器此时不是正常开始关闭而是进程组被 kill
+
+- **事件 ID**: ``kill_server.plugin_stopping_server``
+- **回调参数**: ``PluginServerInterface``
+
+.. _WorldSavedEvent:
+
+WorldSavedEvent
+^^^^^^^^^^^^^^^^
+
+KillServer 创建了一个字面量事件 ``WorldSavedEvent = LiteralEvent("kill_server.world_saved")``
+用以监听服务器是否将世界保存好, 这个事件会在服务器保存世界完成时 (例如 ``/save`` 被调用之后) 触发
+
+- **事件 ID**: ``kill_server.world_saved``
+- **回调参数**: ``PluginServerInterface``