docs: 添加 MCDR 插件文档

[xieyuen]

• 集成 Sphinx 文档构建工具及相关依赖包
• 创建 MCDRpost 插件完整文档页面
• 创建 KillServer 插件完整文档页面
• 添加自定义 Handler API 文档
• 配置文档主题及扩展功能
• 设置多插件文档导航目录
• 添加文档构建脚本和配置文件

[qodo-code-review]

Review Summary by Qodo

Add Sphinx documentation site configuration for MCDR plugins

📝 Documentation

Walkthroughs

Description

• Integrated Sphinx documentation build system with extensions
• Created comprehensive MCDRpost plugin documentation pages
• Created comprehensive KillServer plugin documentation pages
• Added custom Handler API documentation for MCDRpost
• Configured documentation theme, extensions and multi-plugin navigation
• Added documentation build scripts and configuration files

Diagram

flowchart LR
  A["Sphinx Configuration"] --> B["Documentation Build System"]
  B --> C["MCDRpost Docs"]
  B --> D["KillServer Docs"]
  C --> E["README & Custom Handler API"]
  D --> F["README & Usage Guide"]
  G["Build Scripts"] --> B
  H["Dependencies"] --> B

Loading

File Changes

1. docs/source/conf.py ⚙️ Configuration changes +77/-0

Sphinx configuration with extensions and autodoc settings

docs/source/conf.py

---

2. docs/Makefile ⚙️ Configuration changes +20/-0

Unix/Linux documentation build script

docs/Makefile

---

3. docs/make.bat ⚙️ Configuration changes +35/-0

Windows documentation build script

docs/make.bat

---

View more (7)

4. docs/source/index.rst 📝 Documentation +16/-0

Main documentation index with plugin navigation

docs/source/index.rst

---

5. docs/source/mcdrpost/index.rst 📝 Documentation +8/-0

MCDRpost documentation index and table of contents

docs/source/mcdrpost/index.rst

---

6. docs/source/mcdrpost/readme.rst 📝 Documentation +363/-0

MCDRpost comprehensive documentation with usage and configuration

docs/source/mcdrpost/readme.rst

---

7. docs/source/mcdrpost/custom_handler.rst 📝 Documentation +150/-0

MCDRpost custom Handler API documentation with examples

docs/source/mcdrpost/custom_handler.rst

---

8. docs/source/kill_server/index.rst 📝 Documentation +7/-0

KillServer documentation index and table of contents

docs/source/kill_server/index.rst

---

9. docs/source/kill_server/readme.rst 📝 Documentation +138/-0

KillServer comprehensive documentation with features and events

docs/source/kill_server/readme.rst

---

10. pyproject.toml Dependencies +10/-0

Added Sphinx and documentation dependencies

pyproject.toml

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (4) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Docs build crashes ☑ 🐞 Bug ⛯ Reliability

Description

Sphinx 配置无条件遍历仓库根目录下的 dependencies/，当该目录不存在时会在启动阶段抛出 FileNotFoundError，导致文档无法构建。该问题在任何执行
sphinx-build 的环境中都会稳定复现。

Code

docs/source/conf.py[R17-23]

+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))

Evidence

conf.py 对 dependencies.iterdir() 没有做存在性/目录性判断；而该仓库当前没有 dependencies/ 目录，因此 Sphinx 导入配置时就会崩溃。

docs/source/conf.py[17-23]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/source/conf.py` 中对 `dependencies.iterdir()` 的无条件调用会在 `dependencies/` 不存在时抛出 `FileNotFoundError`，导致 Sphinx 无法启动并构建任何文档。
### Issue Context
当前仓库包含 `src/`，但并没有顶层 `dependencies/` 目录；因此该配置在默认仓库布局下必崩。
### Fix Focus Areas
- docs/source/conf.py[17-23]
### Suggested change
- 将遍历逻辑改为：仅当目录存在且为目录时才遍历；且仅将子目录加入 `sys.path`。例如：
- `for base in (src, dependencies):`
- `if base.is_dir():`
 - `for p in base.iterdir():`
   - `if p.is_dir(): sys.path.insert(0, str(p))`
- 若项目确实需要 `dependencies/`，请补充创建目录（至少空目录）并在文档构建说明/脚本中保证其存在。

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. RST directive invalid ☑ 🐞 Bug ✓ Correctness

Description

custom_handler.rst 中的 autoclass 指令把 :no-index: 选项写在同一行，RST 语法不正确，Sphinx 解析该文件时很可能直接报错并中断构建。

Code

docs/source/mcdrpost/custom_handler.rst[R43-45]

+.. autoclass:: mcdrpost.api.OldSoundPlayer
+.. autoclass:: :no-index: mcdrpost.api.Item
+.. autoclass:: mcdrpost.api.Environment

Evidence

当前写法把 directive option 内联在指令行中；按照 reStructuredText/Sphinx 指令格式，选项应当放在后续缩进的选项块里。该行会导致解析失败或至少产生严重警告。

docs/source/mcdrpost/custom_handler.rst[38-45]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/source/mcdrpost/custom_handler.rst` 存在无效的 Sphinx autodoc 指令写法：把 `:no-index:` 写在 `.. autoclass::` 同一行，导致 RST 语法不合法。
### Issue Context
该文件用于生成 API 文档；一旦该页解析失败，将影响整个文档站点构建。
### Fix Focus Areas
- docs/source/mcdrpost/custom_handler.rst[38-45]
### Suggested change
将该段修改为如下格式之一：
**保留 no-index：**

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Markdown links break ☑ 🐞 Bug ✓ Correctness

Description

文档中多处链接指向 .md 文件（如 custom_handler.md、../MCDRpost-migration/README.md），但 Sphinx 配置未启用 Markdown
解析扩展，构建产物中这些链接会指向不存在的页面/资源。

Code

docs/source/mcdrpost/readme.rst[R351-362]

+点击 `此处 <custom_handler.md>`_ 跳转至 MCDRpost 的自定义 Handler 文档
+
+Future
+------
+
+在将来某一个时间（也许是 MCDR 不再支持 Python 3.10 的时候）,
+MCDRpost 将会从 Python 3.10 迁移到 3.12 或者更高版本, 届时 MCDRpost 将会进入 4.x 版本
+
+.. rubric:: 脚注
+
+.. [#f1] Minecraft 1.20.5 用 components 代替了 tag, 导致命令不能执行, Minecraft 报错见 Flyky/MCDRpost#10
+.. [#f2] 理论上使用自定义 Handler 就可以适配任何版本, 但是插件**本身没有兼容**低于 1.13 的版本, 原因见 `Custom Handler <custom_handler.md>`_

Evidence

readme.rst 明确引用 .md 作为站内相对链接目标；同时 conf.py 的 extensions 未包含 MyST/recommonmark 等 Markdown
解析器，因此 .md 不会作为文档源被构建成 HTML 页面，最终形成死链。

docs/source/mcdrpost/readme.rst[20-22]
docs/source/mcdrpost/readme.rst[351-362]
docs/source/conf.py[28-50]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/source/mcdrpost/readme.rst` 中存在对 `.md` 的相对链接，但当前 Sphinx 配置不构建 Markdown 页面，导致站点中出现死链。
### Issue Context
- 站内已经有 `docs/source/mcdrpost/custom_handler.rst`，但文档却链接到了 `custom_handler.md`。
- 还链接到了 `../MCDRpost-migration/README.md`（位于源码目录），Sphinx 默认不会把它当作可导航页面输出。
### Fix Focus Areas
- docs/source/mcdrpost/readme.rst[20-22]
- docs/source/mcdrpost/readme.rst[351-362]
- docs/source/conf.py[28-50]
### Suggested change (recommended)
- 将 `custom_handler.md` 改为指向已存在的 RST 页面，例如：
- 使用 `:doc:`：``:doc:`custom_handler```（或 ``:doc:`mcdrpost/custom_handler``` 视相对路径而定）
- 或直接链接 `custom_handler.html`/`custom_handler`（RST 方式）
- 对 `../MCDRpost-migration/README.md`：
- 若希望在站内可读：把内容迁移/拷贝到 `docs/source/.../*.rst` 并加入 toctree
- 若仅做参考：改为 GitHub 上的绝对链接（指向仓库文件），避免站内死链
### Alternative
- 若必须保留 Markdown：引入 `myst_parser` 并配置 `extensions`/`source_suffix`，同时把需要的 `.md` 文件移动/复制到 `docs/source` 下纳入构建。

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Broken GitHub URL ☑ 🐞 Bug ✓ Correctness

Description

KillServer 文档里存在错误的 GitHub 链接（缺少 .com），会导致用户点击后无法访问。

Code

docs/source/kill_server/readme.rst[R29-30]

+直接安装到 MCDR 的插件文件夹下即可, 可以从 `GitHub <https://github/xieyuen/MCDR-Plugins>`_
+或 `PluginCatalogue <https://mcdreforged.com/zh-CN/plugin/kill_server>`_ 手动下载插件文件

Evidence

链接目标写成了 https://github/...，不是合法的 GitHub 域名。

docs/source/kill_server/readme.rst[29-30]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
KillServer 文档中的 GitHub 链接域名拼写错误，导致死链。
### Issue Context
该链接位于“使用方法”段落，属于高频点击入口。
### Fix Focus Areas
- docs/source/kill_server/readme.rst[29-30]
### Suggested change
将：
- `https://github/xieyuen/MCDR-Plugins`
改为：
- `https://github.com/xieyuen/MCDR-Plugins`

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more