# PR #23337 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[Docs] Sync docs_new with legacy docs and update migration redirects
- 合并时间：2026-04-21 15:15
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/23337

---

# 执行摘要

- 一句话：同步新旧文档并更新迁移重定向，添加 pre-commit 保护遗留目录。
- 推荐动作：建议技术管理者关注重定向规则的可靠性和 pre-commit 钩子的实施，以确保文档迁移顺利进行。工程师可参考新增的扩散模型和硬件平台支持文档，了解最新开发指南，并学习 pre-commit 机制以规范贡献流程。

# 功能与动机

根据 PR 描述，动机是更新 Mintlify 文档迁移状态并保持 `docs_new` 与遗留 `docs` 内容对齐，通过主提交 `a49063241`。这确保迁移顺利进行，路由可预测，避免链接失效。

# 实现拆解

1. **同步文档内容**：同步 `docs_new/docs` 与 `docs` 目录的页面，添加缺失的迁移页面，覆盖高级功能、硬件平台、支持模型等模块。涉及文件如 `docs_new/docs/sglang-diffusion/support_new_models.mdx` 和 `docs_new/docs/supported-models/support_new_models.mdx`。原因：确保内容一致性，便于用户访问最新文档。影响：更新后文档站点内容更完整。
2. **重命名文件**：将 MDX 文件重命名以匹配遗留源文件名，例如将 `JIT_kernels.mdx` 重命名为 `development_jit_kernel_guide.mdx`。涉及文件如 `docs_new/docs/developer_guide/development_jit_kernel_guide.mdx`。原因：保持路由可预测性，便于重定向规则映射。影响：减少迁移过程中的链接断裂风险。
3. **添加 pre-commit 钩子**：新增脚本 `scripts/ci/check_no_docs_changes.py`，在 pre-commit 配置中注册，拒绝 `docs/` 目录下的更改。关键符号：`main` 函数和 `get_staged_paths` 辅助函数。原因：防止贡献者错误修改遗留目录，强制使用新版文档。影响：提升团队维护效率，避免内容分歧。
4. **更新导航和重定向**：更新 `docs_new/docs.json` 文件，刷新导航条目和重定向规则，确保从遗留 Sphinx URL 正确跳转到 Mintlify 站点。原因：验证显示 Mintlify 通配符重定向不可靠，需显式规则保证可靠性。影响：用户访问旧链接时无缝跳转，提升体验。

关键文件：
- `docs_new/docs/sglang-diffusion/support_new_models.mdx`（模块 文档迁移；类别 docs；类型 content-addition；符号 MyModelPipelineConfig, get_freqs_cis, prepare_pos_cond_kwargs, prepare_neg_cond_kwargs）: 新增扩散模型支持文档，指导开发者如何扩展 SGLang Diffusion，涉及架构概述和实现步骤。
- `scripts/ci/check_no_docs_changes.py`（模块 CI 脚本；类别 infra；类型 infrastructure；符号 staged_paths, main）: 新增 pre-commit 钩子脚本，用于阻止对遗留 docs 目录的更改，强制贡献者更新新版文档。
- `docs_new/docs.json`（模块 文档配置；类别 config；类型 configuration）: 更新导航和重定向配置文件，确保迁移后文档站点的链接正确跳转。

关键符号：main, get_staged_paths

## 关键源码片段

### `scripts/ci/check_no_docs_changes.py`

新增 pre-commit 钩子脚本，用于阻止对遗留 docs 目录的更改，强制贡献者更新新版文档。

```python
#!/usr/bin/env python3
import subprocess
import sys

def get_staged_paths() -> list:
    """
    获取当前git暂存区中的所有文件路径列表。
    使用git diff --cached命令提取已暂存但未提交的文件名。
    """
    result = subprocess.run(
        ['git', 'diff', '--cached', '--name-only'],
        capture_output=True,
        text=True,
        check=True  # 如果命令失败则抛出异常
    )
    # 将输出按行分割，并过滤空字符串
    return result.stdout.strip().split('\n') if result.stdout.strip() else []

def main() -> None:
    """
    主函数：遍历暂存文件路径，检查是否包含遗留docs目录。
    如果发现任何以'docs/'开头的路径，则打印错误信息并退出。
    这样，pre-commit钩子会阻止提交，引导用户更新docs_new目录。
    """
    staged_paths = get_staged_paths()
    for path in staged_paths:
        if path.startswith('docs/'):  # 检查路径是否在遗留 docs 目录下
            print(f"Error: Changes to '{path}' are not allowed.")
            print("Please update the corresponding documentation under 'docs_new/' instead.")
            sys.exit(1)  # 退出码非零，表示 pre-commit 检查失败

if __name__ == "__main__":
    main()  # 脚本入口点

```

# 评论区精华

review 评论中，gemini-code-assist[bot] 指出了两个文档细节问题：在 `cache_dit.mdx` 中的 typo 'enable_sperate_cfg' 应改为 'enable_separate_cfg'，以及在 `environment_variables.mdx` 中的语法错误 'only support for' 应改为 'only supported for'。讨论集中在文档正确性，没有重大争议，问题已接受修复。

- Typo in diffusion documentation (correctness): 接受修复，问题已解决。
- Grammar issue in environment variables (correctness): 接受修复，问题已解决。

# 风险与影响

- 风险：技术风险较低。重定向规则更新可能引入 404 错误，但 PR 中已通过本地 HTTP 测试验证 147 条规则无失败，风险可控。pre-commit 钩子可能错误阻止合法更改（如对 `docs/` 目录的必要修复），需确保脚本逻辑准确，避免误报。文档同步可能遗漏页面或引入内容不一致，但通过工具验证（如 mint validate 和 broken-links）可缓解。
- 影响：对用户：文档内容更新，提供更完整和准确的信息（如扩散模型支持、硬件平台指南），改善使用体验。对系统：无运行时影响，仅静态文档和配置变更，不涉及核心代码。对团队：通过 pre-commit 钩子引导贡献者使用新版文档，减少维护负担，确保迁移平滑，并统一文档贡献流程。
- 风险标记：重定向规则风险 , pre-commit 误报

# 关联脉络

- PR #23325 Fix formatting for ACM-VIT in README acknowledgements section: 同为文档修复 PR，涉及文档格式调整，与本 PR 的文档同步目标相关。
- PR #23312 Docs/url redirect: 直接相关，都是文档重定向和迁移工作，本 PR 在此基础上更新重定向规则。
- PR #23238 [NPU] [DOC] Quick start doc for Ascend NPU: 涉及硬件平台文档更新，本 PR 同步了该内容到 docs_new 目录，关联迁移过程。