执行摘要

本PR为旧版文档网站（https://sgl-project.github.io）添加弃用通知横幅，通过JavaScript和CSS实现前端提示，并更新CI脚本以允许相关文件修改，属于常规文档维护工作，风险较低。

功能与动机

动机是引导用户从旧版文档网站迁移至新站点（https://docs.sglang.io），提升用户体验和维护效率。根据PR body，添加横幅是为了明确弃用时间表，同时添加LEGACY_DOCS_ALLOWLIST以绕过pre-commit钩子，便于后续维护。

实现拆解

1. 新增JavaScript横幅逻辑：在docs/_static/js/deprecation_banner.js中定义两个核心函数：
   • buildNewDocsUrl()：根据当前URL构建新文档站点链接。
   • addDeprecationBanner()：创建并插入横幅元素到页面顶部。
     

     // 示例代码片段：构建新 URL 逻辑
     function buildNewDocsUrl() {
         var href = window.location.href;
         if (href === oldOrigin || href.indexOf(oldOrigin + "/") === 0) {
             return href.replace(oldOrigin, newOrigin); // 替换旧域名
         }
         return newOrigin + window.location.pathname + window.location.search + window.location.hash; // 基于路径构建
     }
     

2. 更新Sphinx配置：修改docs/conf.py，在html_js_files中添加js/deprecation_banner.js，确保脚本被加载。
3. 添加CSS样式：在docs/_static/css/custom_log.css中定义.sglang-docs-deprecation-banner类，设置背景色、边框和链接样式，确保横幅视觉突出。
4. 调整CI脚本：修改scripts/ci/check_no_docs_changes.py，添加LEGACY_DOCS_ALLOWLIST允许列表，包含横幅相关文件，避免pre-commit检查阻塞维护。

关键源码片段

docs/_static/js/deprecation_banner.js

新增核心JavaScript逻辑，负责构建新文档URL和添加弃用横幅，是功能实现的关键。

(function () {
    "use strict";
​
    var oldOrigin = "https://sgl-project.github.io";
    var newOrigin = "https://docs.sglang.io";
​
    function buildNewDocsUrl() {
        var href = window.location.href;
        // 如果当前 URL 匹配旧版站点，则替换为新站点 URL
        if (href === oldOrigin || href.indexOf(oldOrigin + "/") === 0) {
            return href.replace(oldOrigin, newOrigin);
        }
        // 否则，基于路径构建新 URL
        return newOrigin + window.location.pathname + window.location.search + window.location.hash;
    }
​
    function addDeprecationBanner() {
        // 避免重复添加横幅
        if (document.getElementById("sglang-docs-deprecation-banner")) {
            return;
        }
​
        var link = document.createElement("a");
        link.href = buildNewDocsUrl(); // 设置链接到新文档站点
        link.textContent = link.href;
​
        var banner = document.createElement("div");
        banner.id = "sglang-docs-deprecation-banner";
        banner.className = "sglang-docs-deprecation-banner";
        banner.setAttribute("role", "status");
        banner.setAttribute("aria-live", "polite");
​
        var prefix = document.createTextNode(
            "This legacy documentation site will be deprecated soon. Please use the new SGLang documentation at "
        );
        var suffix = document.createTextNode(".");
​
        banner.appendChild(prefix);
        banner.appendChild(link);
        banner.appendChild(suffix);
​
        // 将横幅插入到页面顶部
        document.body.insertBefore(banner, document.body.firstChild);
    }
​
    // 在 DOM 加载完成后添加横幅
    if (document.readyState === "loading") {
        document.addEventListener("DOMContentLoaded", addDeprecationBanner);
    } else {
        addDeprecationBanner();
    }
})();

评论区精华

Review中无实质技术讨论，仅由wisclmy0611批准，表明变更被直接接受，无争议点。

风险与影响

• 技术风险：横幅JavaScript依赖标准DOM API，但可能在不支持某些特性的旧浏览器中失效；CSS样式可能与现有文档主题冲突；CI脚本变更若未充分测试，可能意外影响其他文档文件的检查流程。
• 影响范围：用户访问旧版网站时将看到醒目提示，促进迁移；系统前端添加了轻量级交互元素；团队维护更便捷，允许特定文件绕过限制。

关联脉络

与近期文档相关PR（如#23437添加重定向、#23486更新模型文档）一脉相承，反映团队在文档迁移和维护上的持续投入，旨在提升文档质量和用户体验。