From bfe5acb8eb8e50ad54c1de7b79521c521f1702bf Mon Sep 17 00:00:00 2001
From: justbin-code <jiazhibin48@gmail.com>
Date: Tue, 17 Mar 2026 06:56:58 +0000
Subject: [PATCH 1/3] Implement configurable independent community sub-sites
 with modular navigation base on verl

---
 .gitmodules            |   1 +
 Makefile               |   3 +-
 _repos/verl            |   2 +-
 _static/custom.css     |  32 +++++-
 _templates/layout.html | 118 +++++++++++++++++++
 conf.py                |  67 ++++++++++-
 index.rst              |   2 +-
 requirements.txt       |   3 +-
 sources/verl/index.rst | 253 +++++++++++++++++++++++++++++++++++++++--
 9 files changed, 466 insertions(+), 15 deletions(-)
 create mode 100644 _templates/layout.html

diff --git a/.gitmodules b/.gitmodules
index 454b7945..297ce922 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,6 +1,7 @@
 [submodule "_repos/verl"]
 	path = _repos/verl
 	url = https://github.com/volcengine/verl.git
+	branch = main
 [submodule "_repos/LLaMA-Factory"]
 	path = _repos/LLaMA-Factory
 	url = https://github.com/the-seeds/LLaMA-Factory-Doc.git
diff --git a/Makefile b/Makefile
index 3495e930..48efeeba 100644
--- a/Makefile
+++ b/Makefile
@@ -61,7 +61,8 @@ sync-onnxruntime-doc:
 # Initialize submodules if not exists (use pinned commits for reproducibility)
 _repos/verl _repos/VeOmni _repos/LLaMA-Factory _repos/ms-swift:
 	@echo "Initializing submodules..."
-	@git submodule update --init
+	@git submodule sync --recursive
+	@git submodule update --init --remote
 
 # Copy documentation from submodules
 copy-docs: _repos/verl _repos/VeOmni _repos/LLaMA-Factory _repos/ms-swift
diff --git a/_repos/verl b/_repos/verl
index 07d40332..77476af8 160000
--- a/_repos/verl
+++ b/_repos/verl
@@ -1 +1 @@
-Subproject commit 07d403321fb32aedb0b8eff6e23ecfabed559174
+Subproject commit 77476af84cc074edf5a6437f8d5ea418d7a54916
diff --git a/_static/custom.css b/_static/custom.css
index b3b2e0c9..3847cc5e 100644
--- a/_static/custom.css
+++ b/_static/custom.css
@@ -362,4 +362,34 @@ body.onnxruntime-quickstart-page .rst-content .highlight {
 }
 
 
-/* card-icon 样式已移至 index.rst 中统一管理 */
\ No newline at end of file
+/* =========================================================
+   独立社区侧边栏专属样式
+   ========================================================= */
+
+#independent-sidebar .custom-sidebar-caption {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    font-size: 85%;
+    color: #0066cc; 
+    font-weight: 700;
+    text-transform: uppercase;
+    margin-top: 1.5em;
+    margin-bottom: 0.5em;
+    padding-left: 15px;
+    letter-spacing: 0.5px;
+}
+
+#independent-sidebar ul {
+    margin-bottom: 0 !important;
+}
+
+/* 覆盖菜单基础项的 padding，使其靠左贴齐 */
+#independent-sidebar ul li.toctree-l1 > a {
+    padding-left: 15px !important;
+}
+
+#independent-sidebar ul li.toctree-l1.current > a {
+    background: #e6f0fa; /* 当前选中项高亮背景色 */
+    color: #0066cc;
+    border-left: 4px solid #0066cc;
+    padding-left: 11px !important; /* 减去边框宽度保持对齐 */
+}
diff --git a/_templates/layout.html b/_templates/layout.html
new file mode 100644
index 00000000..b470b03c
--- /dev/null
+++ b/_templates/layout.html
@@ -0,0 +1,118 @@
+{% extends "!layout.html" %}
+
+{% block menu %}
+{% if is_independent %}
+    <!-- 1. 将原本庞大的全局菜单隐藏起来，作为数据源 -->
+    <div id="temp-menu-holder" style="display: none;">
+        {{ super() }}
+    </div>
+
+    <!-- 2. 独立站点独立侧边栏容器（直接插入在原菜单位置） -->
+    <div id="independent-sidebar"></div>
+
+    <script>
+    document.addEventListener('DOMContentLoaded', function() {
+        const mapping = {{ comm_config.get('sidebar_mapping', {}) | tojson | safe }};
+        const commId = '{{ current_community_id }}';
+        
+        // 获取数据源和目标容器
+        const globalMenu = document.getElementById('temp-menu-holder');
+        const targetContainer = document.getElementById('independent-sidebar');
+
+        if (!globalMenu) return;
+
+        // 步骤 A: 找到当前社区的主节点 (通常带有 .current 类)
+        let activeL1 = globalMenu.querySelector('li.toctree-l1.current');
+
+        // 兜底策略: 如果没有 .current (如强制刷新等边缘情况)，通过链接匹配
+        if (!activeL1 || !activeL1.querySelector('a').href.includes('/sources/' + commId + '/')) {
+            const links = globalMenu.querySelectorAll('li.toctree-l1 > a');
+            for (let i = 0; i < links.length; i++) {
+                if (links[i].href.includes('/sources/' + commId + '/')) {
+                    activeL1 = links[i].closest('li');
+                    break;
+                }
+            }
+        }
+
+        if (activeL1) {
+            // 步骤 B: 找到属于这个社区的所有子页面 (<ul>)
+            const subMenu = activeL1.querySelector('ul');
+            
+            if (subMenu && subMenu.children.length > 0) {
+                let currentGroup = null;
+                let currentUl = null;
+
+                // 步骤 C: 遍历所有的子页面，将它们分组并插入到独立侧边栏中
+                const items = Array.from(subMenu.children);
+                items.forEach(item => {
+                    if (item.tagName.toLowerCase() !== 'li') return;
+
+                    const link = item.querySelector('a');
+                    if (!link) return;
+
+                    const fullUrl = link.href;
+                    let matchedFolder = null;
+
+                    // 匹配 conf.py 中配置的文件夹路径
+                    // 使用更精确的匹配：sources/{commId}/{folder}/ 或 sources/_generated/sources/{commId}/{folder}/
+                    for (const folder in mapping) {
+                        const pattern1 = `/sources/${commId}/${folder}/`;
+                        const pattern2 = `/sources/_generated/sources/${commId}/${folder}/`;
+                        if (fullUrl.includes(pattern1) || fullUrl.includes(pattern2)) {
+                            matchedFolder = folder;
+                            break;
+                        }
+                    }
+
+                    // 如果有的文件放在根目录没匹配到，归入 default
+                    if (!matchedFolder) {
+                        matchedFolder = currentGroup || 'default';
+                    }
+
+                    // 步骤 D: 遇到新分组时，创建大标题和新的 <ul>
+                    if (currentGroup !== matchedFolder) {
+                        if (mapping[matchedFolder]) {
+                            const caption = document.createElement('p');
+                            caption.className = 'caption custom-sidebar-caption';
+                            caption.innerHTML = `<span class="caption-text">${mapping[matchedFolder]}</span>`;
+                            targetContainer.appendChild(caption);
+                        }
+
+                        currentUl = document.createElement('ul');
+                        targetContainer.appendChild(currentUl);
+                        currentGroup = matchedFolder;
+                    }
+
+                    // 步骤 E: 智能动态提升整棵树的级数，完美支持长文档的内部 H2/H3 目录显示
+                    // 找出该节点及其内部所有的级联列表项
+                    const allTocItems = [item, ...item.querySelectorAll('[class*="toctree-l"]')];
+                    allTocItems.forEach(el => {
+                        // 将 toctree-l(X) 动态替换为 toctree-l(X-1)
+                        el.className = el.className.replace(/toctree-l(\d+)/g, function(match, level) {
+                            const newLevel = parseInt(level, 10) - 1;
+                            return 'toctree-l' + newLevel;
+                        });
+                    });
+
+                    // 挂载到对应独立社区的菜单中
+                    if (currentUl) {
+                        currentUl.appendChild(item);
+                    }
+                });
+
+                // 步骤 F: 彻底删除隐蔽的全局菜单
+                globalMenu.remove();
+                return;
+            }
+        }
+
+        // 异常兜底: 如果出现极端的解析失败（比如网络延迟），取消隐藏，确保文档菜单可用
+        globalMenu.style.display = 'block';
+    });
+    </script>
+{% else %}
+    <!-- 非独立社区页面，直接按普通 Sphinx 逻辑渲染 -->
+    {{ super() }}
+{% endif %}
+{% endblock %}
\ No newline at end of file
diff --git a/conf.py b/conf.py
index 3b0a4410..43d6968d 100644
--- a/conf.py
+++ b/conf.py
@@ -30,14 +30,32 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'recommonmark',
     'sphinx.ext.autodoc',
     'sphinxext.remoteliteralinclude',
     'sphinx_copybutton',
     'sphinx_markdown_tables',
     "sphinx_design",
+    'myst_parser',
 ]
 
+# 这一行非常重要，它允许 MyST 处理复杂的标题层级
+myst_heading_anchors = 3
+
+# 允许在 RST 中嵌入 Markdown 内容
+myst_enable_extensions = [
+    "colon_fence",
+    "html_image",
+]
+
+# conf.py
+html_theme_options = {
+    # 仅显示当前页面所属的导航树，不显示全局无关节点
+    'collapse_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False,
+}
+
 # 模板路径设置
 templates_path = ['_templates']
 autosummary_generate = True
@@ -180,6 +198,53 @@ def generate_api_doc():
     with open(rst_filename, 'w', encoding='utf-8') as f:
         f.write(rendered_content)
  
+# =========================================================
+# 独立社区页面全局配置 (核心机制：高度可配置化)
+# =========================================================
+html_context = {
+    'independent_communities': {
+        'verl': {
+            'display_name': 'verl',
+            'sidebar_mapping': {
+                'quick_start': '🚀 快速入门',
+                'features': '📚 特性指南',
+                'profiling': '⚡ 调优指南',
+                'examples': '📊 应用与调优实践',
+                'faq': '🔆 故障排查(FAQ)',
+                'contribution_guide': '🔧 开源开发'
+            }
+        },
+    }
+}
+
+# 【新增核心代码】：Sphinx 页面上下文注入 Hook
+def update_page_context(app, pagename, templatename, context, doctree):
+    """
+    拦截页面渲染，判断当前路径是否属于独立社区。
+    如果是，向 Jinja 模板注入 is_independent 和对应的 comm_config 变量。
+    支持两种路径格式：
+    - sources/verl/... (手写页面)
+    - sources/_generated/sources/verl/... (从子模块拉取的页面)
+    """
+    communities = context.get('independent_communities', {})
+    context['is_independent'] = False
+
+    for comm_id, comm_info in communities.items():
+        # 匹配两种路径格式
+        if pagename.startswith(f"sources/{comm_id}") or pagename.startswith(f"sources/_generated/sources/{comm_id}"):
+            context['is_independent'] = True
+            context['current_community_id'] = comm_id
+            context['comm_config'] = comm_info
+            break
+
+def setup(app):
+    app.add_css_file('custom.css')
+    app.add_js_file('package_info.js')
+    app.add_js_file('statistics.js')
+    
+    # 【新增 Hook 注册】
+    app.connect('html-page-context', update_page_context)
+
 # 在 Sphinx 构建之前调用该函数生成 API 文档
 try:
     generate_api_doc()
diff --git a/index.rst b/index.rst
index 35887271..76d2d322 100644
--- a/index.rst
+++ b/index.rst
@@ -207,7 +207,7 @@
       <div class="project-card">
          <div class="card-top"><div class="card-icon" style="background-image: url('_static/images/volcano.png')"></div><h3 class="card-title">verl</h3></div>
          <p class="card-desc">用于 LLM 的强化学习训练库，适配昇腾并行计算方案。</p>
-         <div class="card-footer"><a href="https://github.com/volcengine/verl">官方链接</a><span class="split">|</span><a href="sources/_generated/sources/verl/ascend_quick_start.html">安装指南</a><span class="split">|</span><a href="sources/_generated/sources/verl/ascend_quick_start.html">快速上手</a></div>
+         <div class="card-footer"><a href="https://github.com/volcengine/verl">官方链接</a><span class="split">|</span><a href="sources/_generated/sources/verl/quick_start/ascend_quick_start.html">安装指南</a><span class="split">|</span><a href="sources/_generated/sources/verl/quick_start/ascend_quick_start.html">快速上手</a></div>
       </div>
 
    </div>
diff --git a/requirements.txt b/requirements.txt
index 9c9aba78..e0c39870 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -8,4 +8,5 @@ sphinx_markdown_tables
 sphinx-design
 torch==2.5.1+cpu; platform_machine == "x86_64"
 torch==2.5.1; platform_machine == "aarch64"
-torch_npu==2.5.1rc1; sys_platform == "linux"
+torch_npu==2.5.1rc1;sys_platform == "linux"
+myst_parser
\ No newline at end of file
diff --git a/sources/verl/index.rst b/sources/verl/index.rst
index 10a73b06..ddb1b0c0 100644
--- a/sources/verl/index.rst
+++ b/sources/verl/index.rst
@@ -1,12 +1,247 @@
-verl
-============
+verl - 大模型强化学习训练框架
+============================================
+
+.. raw:: html
+
+   <style>
+      /* 样式隔离：仅作用于首页入口 */
+      #verl-portal {
+          --v-primary: #0066cc;
+          --v-secondary: #00a86b;
+          --v-accent: #ff6b35;
+          --v-purple: #9d4edd;
+          --v-text-main: #1a1a1a;
+          --v-text-sub: #666666;
+          --v-border: #e1e4e8;
+          --v-bg-light: #f6f8fa;
+          font-family: -apple-system, system-ui, Segoe UI, Roboto, Helvetica;
+      }
+
+      /* 英雄区 */
+      .verl-hero {
+          background: linear-gradient(135deg, var(--v-primary) 0%, #004a99 100%);
+          color: white;
+          padding: 60px 40px;
+          border-radius: 12px;
+          margin: 20px 0 40px 0;
+          text-align: center;
+          box-shadow: 0 8px 24px rgba(0, 102, 204, 0.15);
+      }
+      .verl-hero h1 { color: white !important; border: none !important; margin: 0 0 15px 0 !important; font-size: 2.8rem !important; }
+      .verl-hero-subtitle { font-size: 1.2rem; opacity: 0.95; margin-bottom: 30px; }
+      .verl-hero-buttons { display: flex; gap: 15px; justify-content: center; flex-wrap: wrap; }
+      .verl-btn {
+          padding: 12px 30px; border-radius: 6px; text-decoration: none !important;
+          font-weight: 600; transition: all 0.3s ease; border: 2px solid white;
+      }
+      .verl-btn-primary { background: white; color: var(--v-primary) !important; }
+      .verl-btn-secondary { background: transparent; color: white !important; }
+      .verl-btn:hover { transform: translateY(-2px); box-shadow: 0 8px 16px rgba(0,0,0,0.2); }
+
+      /* 核心特性 - 恢复原版 6 卡片风格 */
+      .verl-section-title { text-align: center; color: var(--v-primary); margin: 50px 0 30px 0; font-size: 2rem; border: none !important; }
+      .verl-features {
+          display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+          gap: 25px; margin-bottom: 50px;
+      }
+      .verl-feature-card {
+          background: white; border: 1px solid var(--v-border);
+          border-radius: 10px; padding: 25px; transition: all 0.3s ease;
+      }
+      .verl-feature-card:hover { border-color: var(--v-primary); transform: translateY(-4px); box-shadow: 0 12px 24px rgba(0, 102, 204, 0.1); }
+      .verl-feature-icon { font-size: 2.5rem; margin-bottom: 15px; }
+      .verl-feature-card h3 { color: var(--v-primary); margin: 0 0 12px 0 !important; font-size: 1.3rem !important; border: none !important; }
+      .verl-feature-card p { color: var(--v-text-sub); line-height: 1.6; margin: 0; font-size: 0.95rem; }
+
+      /* 开发者路径 */
+      .verl-path-wrapper {
+          background: var(--v-bg-light); border-radius: 12px;
+          padding: 40px 25px; margin: 50px 0;
+      }
+      .verl-path-container {
+          display: flex; flex-wrap: wrap; gap: 20px; justify-content: center;
+      }
+      .verl-path-step {
+          background: white; border-top: 4px solid var(--v-primary);
+          padding: 20px; border-radius: 8px; flex: 1 1 220px; max-width: 280px;
+          box-shadow: 0 4px 6px rgba(0,0,0,0.05); transition: 0.3s;
+      }
+      .verl-path-step:nth-child(2) { border-top-color: var(--v-secondary); }
+      .verl-path-step:nth-child(3) { border-top-color: var(--v-accent); }
+      .verl-path-step:nth-child(4) { border-top-color: var(--v-purple); }
+      .verl-path-step:hover { transform: translateY(-5px); box-shadow: 0 8px 15px rgba(0,0,0,0.1); }
+      .verl-step-num {
+          display: inline-block; width: 30px; height: 30px; background: var(--v-primary);
+          color: white; border-radius: 50%; text-align: center; line-height: 30px;
+          font-weight: bold; margin-bottom: 15px;
+      }
+      .verl-path-step:nth-child(2) .verl-step-num { background: var(--v-secondary); }
+      .verl-path-step:nth-child(3) .verl-step-num { background: var(--v-accent); }
+      .verl-path-step:nth-child(4) .verl-step-num { background: var(--v-purple); }
+      .verl-path-step h4 { margin: 0 0 10px 0 !important; border: none !important; font-size: 1.1rem !important; }
+      .verl-path-step p { color: var(--v-text-sub); font-size: 0.9rem; line-height: 1.5; margin: 0; }
+
+      /* 快速开始卡片跳转 */
+      .verl-quick-grid {
+          display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+          gap: 20px; margin-top: 30px;
+      }
+      .verl-quick-card {
+          text-decoration: none !important; border: 1px solid var(--v-border);
+          padding: 25px; border-radius: 10px; text-align: center; transition: 0.3s; background: white;
+      }
+      .verl-quick-card:hover { border-color: var(--v-primary); transform: scale(1.03); box-shadow: 0 10px 20px rgba(0,102,204,0.1); }
+      .verl-quick-card h4 { color: var(--v-primary); margin: 15px 0 0 0 !important; border: none !important; }
+
+      @media (max-width: 768px) {
+          .verl-hero h1 { font-size: 2rem !important; }
+          .verl-quick-grid { grid-template-columns: 1fr 1fr; }
+      }
+   </style>
+
+   <div id="verl-portal">
+      <!-- 英雄区 -->
+      <div class="verl-hero">
+         <h1>🚀 verl</h1>
+         <p class="verl-hero-subtitle">灵活、高效的大语言模型强化学习训练框架</p>
+         <div class="verl-hero-buttons">
+            <a href="https://github.com/volcengine/verl" class="verl-btn verl-btn-primary">📖 GitHub 仓库</a>
+         </div>
+      </div>
+
+      <!-- 核心特性 -->
+      <h2 class="verl-section-title">✨ 核心特性</h2>
+      <div class="verl-features">
+         <div class="verl-feature-card">
+            <div class="verl-feature-icon">🧬</div>
+            <h3>多样化 RL 算法</h3>
+            <p>混合编程模型结合单控制器和多控制器范式，实现灵活表示和高效复杂后训练数据流执行</p>
+         </div>
+         <div class="verl-feature-card">
+            <div class="verl-feature-icon">🔗</div>
+            <h3>无缝框架集成</h3>
+            <p>解耦计算和数据依赖，支持 PyTorch FSDP、Megatron-LM、vLLM 和 SGLang</p>
+         </div>
+         <div class="verl-feature-card">
+            <div class="verl-feature-icon">📊</div>
+            <h3>灵活设备映射</h3>
+            <p>支持将模型放置在不同的 GPU/NPU 集合上，实现高效的资源利用和并行化</p>
+         </div>
+         <div class="verl-feature-card">
+            <div class="verl-feature-icon">⚡</div>
+            <h3>业界领先吞吐量</h3>
+            <p>通过集成 SOTA LLM 训练和推理框架，实现高生成和训练吞吐量</p>
+         </div>
+         <div class="verl-feature-card">
+            <div class="verl-feature-icon">🤗</div>
+            <h3>HuggingFace 集成</h3>
+            <p>与 HuggingFace 生态无缝适配，支持 600+ 开源模型即用</p>
+         </div>
+         <div class="verl-feature-card">
+            <div class="verl-feature-icon">🎯</div>
+            <h3>昇腾 NPU 支持</h3>
+            <p>深度适配华为昇腾设备，充分发挥国产芯片性能</p>
+         </div>
+      </div>
+
+      <!-- 开发者路径 -->
+      <div class="verl-path-wrapper">
+         <h2 style="text-align:center; color:var(--v-primary); margin-bottom:35px; border:none !important;">🎓 RL 后训练开发者学习路径</h2>
+         <div class="verl-path-container">
+            <div class="verl-path-step">
+               <span class="verl-step-num">1</span>
+               <h4>基础概念</h4>
+               <p>理解 RLHF, PPO/DPO 算法原理及奖励模型设计基础</p>
+            </div>
+            <div class="verl-path-step">
+               <span class="verl-step-num">2</span>
+               <h4>快速上手</h4>
+               <p>昇腾环境搭建、模型加载与基础微调单卡示例</p>
+            </div>
+            <div class="verl-path-step">
+               <span class="verl-step-num">3</span>
+               <h4>高级特性</h4>
+               <p>多卡分布式训练调优、性能瓶颈分析与自定义算法</p>
+            </div>
+            <div class="verl-path-step">
+               <span class="verl-step-num">4</span>
+               <h4>生产部署</h4>
+               <p>推理优化加速、模型评估基准与生产环境发布策略</p>
+            </div>
+         </div>
+      </div>
+
+      <!-- 快速开始 -->
+      <h2 class="verl-section-title">🚀 快速开始</h2>
+      <div class="verl-quick-grid">
+         <a href="../_generated/sources/verl/quick_start/ascend_quick_start.html" class="verl-quick-card">
+            <div style="font-size: 2rem;">📚</div>
+            <h4>快速入门</h4>
+         </a>
+         <a href="../_generated/sources/verl/features/ascend_backend_features.html" class="verl-quick-card">
+            <div style="font-size: 2rem;">🔧</div>
+            <h4>特性指南</h4>
+         </a>
+         <a href="../_generated/sources/verl/examples/ascend_performance_analysis_guide.html" class="verl-quick-card">
+            <div style="font-size: 2rem;">⚙️</div>
+            <h4>应用实践</h4>
+         </a>
+         <a href="../_generated/sources/verl/contribution_guide/ascend_ci_guide_zh.html" class="verl-quick-card">
+            <div style="font-size: 2rem;">👨‍💻</div>
+            <h4>开源开发</h4>
+         </a>
+      </div>
+   </div>
+
+----
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: 🚀 快速入门
+
+   ../_generated/sources/verl/quick_start/ascend_quick_start
+   ../_generated/sources/verl/quick_start/ascend_sglang_quick_start
+   ../_generated/sources/verl/quick_start/dockerfile_build_guidance
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: 📚 特性指南
+
+   ../_generated/sources/verl/features/ascend_backend_features
+   ../_generated/sources/verl/features/ascend_consistency
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: ⚡ 调优指南
+
+   ../_generated/sources/verl/profiling/ascend_profiling_zh
+   ../_generated/sources/verl/profiling/ascend_profiling_en
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: 📊 应用与调优践实
+
+   ../_generated/sources/verl/examples/ascend_performance_analysis_guide
+   ../_generated/sources/verl/examples/ascend_sglang_best_practices
+   ../_generated/sources/verl/examples/dapo_multi_model_optimization_practice
+   ../_generated/sources/verl/examples/ascend_retool_best_pratice
+   ../_generated/sources/verl/examples/run_qwen3_32B_megatron_1k_256k_npu
+   ../_generated/sources/verl/examples/gspo_optimization_practice
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: 🔆 故障排查(FAQ)
+
+   ../_generated/sources/verl/faq/faq
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
+   :hidden:
+   :caption: 🔧 开源开发
 
-   ../_generated/sources/verl/ascend_quick_start
-   ../_generated/sources/verl/ascend_sglang_quick_start
-   ../_generated/sources/verl/dockerfile_build_guidance
-   ../_generated/sources/verl/ascend_profiling_en
-   ../_generated/sources/verl/ascend_profiling_zh
-   ../_generated/sources/verl/ascend_consistency
+   ../_generated/sources/verl/contribution_guide/ascend_ci_guide_zh
\ No newline at end of file

From f88b189a10b8ab1d63bdf7158a0709c281a53d7d Mon Sep 17 00:00:00 2001
From: justbin-code <jiazhibin48@gmail.com>
Date: Thu, 19 Mar 2026 07:54:30 +0000
Subject: [PATCH 2/3] refactor(verl): simplify landing page

---
 sources/verl/index.rst | 165 +++++++++++++----------------------------
 1 file changed, 51 insertions(+), 114 deletions(-)

diff --git a/sources/verl/index.rst b/sources/verl/index.rst
index ddb1b0c0..ecd91308 100644
--- a/sources/verl/index.rst
+++ b/sources/verl/index.rst
@@ -1,4 +1,4 @@
-verl - 大模型强化学习训练框架
+verl
 ============================================
 
 .. raw:: html
@@ -38,64 +38,46 @@ verl - 大模型强化学习训练框架
       .verl-btn-secondary { background: transparent; color: white !important; }
       .verl-btn:hover { transform: translateY(-2px); box-shadow: 0 8px 16px rgba(0,0,0,0.2); }
 
-      /* 核心特性 - 恢复原版 6 卡片风格 */
-      .verl-section-title { text-align: center; color: var(--v-primary); margin: 50px 0 30px 0; font-size: 2rem; border: none !important; }
-      .verl-features {
-          display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-          gap: 25px; margin-bottom: 50px;
+      /* 快速开始卡片 */
+      .verl-section-title { text-align: center; color: var(--v-primary); margin: 40px 0 25px 0; font-size: 1.8rem; border: none !important; }
+      .verl-quick-grid {
+          display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+          gap: 20px; margin-bottom: 50px;
       }
-      .verl-feature-card {
-          background: white; border: 1px solid var(--v-border);
-          border-radius: 10px; padding: 25px; transition: all 0.3s ease;
+      .verl-quick-card {
+          text-decoration: none !important; border: 1px solid var(--v-border);
+          padding: 28px 20px; border-radius: 10px; text-align: center; transition: 0.3s; background: white;
       }
-      .verl-feature-card:hover { border-color: var(--v-primary); transform: translateY(-4px); box-shadow: 0 12px 24px rgba(0, 102, 204, 0.1); }
-      .verl-feature-icon { font-size: 2.5rem; margin-bottom: 15px; }
-      .verl-feature-card h3 { color: var(--v-primary); margin: 0 0 12px 0 !important; font-size: 1.3rem !important; border: none !important; }
-      .verl-feature-card p { color: var(--v-text-sub); line-height: 1.6; margin: 0; font-size: 0.95rem; }
+      .verl-quick-card:hover { border-color: var(--v-primary); transform: scale(1.03); box-shadow: 0 10px 20px rgba(0,102,204,0.1); }
+      .verl-quick-card-icon { font-size: 2.2rem; margin-bottom: 12px; }
+      .verl-quick-card h4 { color: var(--v-primary); margin: 0 0 8px 0 !important; border: none !important; font-size: 1.1rem !important; }
+      .verl-quick-card p { color: var(--v-text-sub); font-size: 0.85rem; margin: 0; line-height: 1.4; }
 
-      /* 开发者路径 */
-      .verl-path-wrapper {
+      /* 核心特性 - 紧凑标签行 */
+      .verl-features-compact {
           background: var(--v-bg-light); border-radius: 12px;
-          padding: 40px 25px; margin: 50px 0;
-      }
-      .verl-path-container {
-          display: flex; flex-wrap: wrap; gap: 20px; justify-content: center;
-      }
-      .verl-path-step {
-          background: white; border-top: 4px solid var(--v-primary);
-          padding: 20px; border-radius: 8px; flex: 1 1 220px; max-width: 280px;
-          box-shadow: 0 4px 6px rgba(0,0,0,0.05); transition: 0.3s;
+          padding: 30px 25px; margin-bottom: 20px;
       }
-      .verl-path-step:nth-child(2) { border-top-color: var(--v-secondary); }
-      .verl-path-step:nth-child(3) { border-top-color: var(--v-accent); }
-      .verl-path-step:nth-child(4) { border-top-color: var(--v-purple); }
-      .verl-path-step:hover { transform: translateY(-5px); box-shadow: 0 8px 15px rgba(0,0,0,0.1); }
-      .verl-step-num {
-          display: inline-block; width: 30px; height: 30px; background: var(--v-primary);
-          color: white; border-radius: 50%; text-align: center; line-height: 30px;
-          font-weight: bold; margin-bottom: 15px;
+      .verl-features-compact-title {
+          text-align: center; color: var(--v-primary); margin: 0 0 20px 0;
+          font-size: 1.1rem; font-weight: 600; border: none !important;
       }
-      .verl-path-step:nth-child(2) .verl-step-num { background: var(--v-secondary); }
-      .verl-path-step:nth-child(3) .verl-step-num { background: var(--v-accent); }
-      .verl-path-step:nth-child(4) .verl-step-num { background: var(--v-purple); }
-      .verl-path-step h4 { margin: 0 0 10px 0 !important; border: none !important; font-size: 1.1rem !important; }
-      .verl-path-step p { color: var(--v-text-sub); font-size: 0.9rem; line-height: 1.5; margin: 0; }
-
-      /* 快速开始卡片跳转 */
-      .verl-quick-grid {
-          display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-          gap: 20px; margin-top: 30px;
+      .verl-feature-tags {
+          display: flex; flex-wrap: wrap; gap: 12px; justify-content: center;
       }
-      .verl-quick-card {
-          text-decoration: none !important; border: 1px solid var(--v-border);
-          padding: 25px; border-radius: 10px; text-align: center; transition: 0.3s; background: white;
+      .verl-feature-tag {
+          display: flex; align-items: center; gap: 8px;
+          background: white; border: 1px solid var(--v-border);
+          border-radius: 20px; padding: 8px 16px;
+          font-size: 0.9rem; color: var(--v-text-main);
+          white-space: nowrap;
       }
-      .verl-quick-card:hover { border-color: var(--v-primary); transform: scale(1.03); box-shadow: 0 10px 20px rgba(0,102,204,0.1); }
-      .verl-quick-card h4 { color: var(--v-primary); margin: 15px 0 0 0 !important; border: none !important; }
+      .verl-feature-tag span { font-size: 1.1rem; }
 
       @media (max-width: 768px) {
           .verl-hero h1 { font-size: 2rem !important; }
           .verl-quick-grid { grid-template-columns: 1fr 1fr; }
+          .verl-feature-tags { gap: 8px; }
       }
    </style>
 
@@ -109,88 +91,43 @@ verl - 大模型强化学习训练框架
          </div>
       </div>
 
-      <!-- 核心特性 -->
-      <h2 class="verl-section-title">✨ 核心特性</h2>
-      <div class="verl-features">
-         <div class="verl-feature-card">
-            <div class="verl-feature-icon">🧬</div>
-            <h3>多样化 RL 算法</h3>
-            <p>混合编程模型结合单控制器和多控制器范式，实现灵活表示和高效复杂后训练数据流执行</p>
-         </div>
-         <div class="verl-feature-card">
-            <div class="verl-feature-icon">🔗</div>
-            <h3>无缝框架集成</h3>
-            <p>解耦计算和数据依赖，支持 PyTorch FSDP、Megatron-LM、vLLM 和 SGLang</p>
-         </div>
-         <div class="verl-feature-card">
-            <div class="verl-feature-icon">📊</div>
-            <h3>灵活设备映射</h3>
-            <p>支持将模型放置在不同的 GPU/NPU 集合上，实现高效的资源利用和并行化</p>
-         </div>
-         <div class="verl-feature-card">
-            <div class="verl-feature-icon">⚡</div>
-            <h3>业界领先吞吐量</h3>
-            <p>通过集成 SOTA LLM 训练和推理框架，实现高生成和训练吞吐量</p>
-         </div>
-         <div class="verl-feature-card">
-            <div class="verl-feature-icon">🤗</div>
-            <h3>HuggingFace 集成</h3>
-            <p>与 HuggingFace 生态无缝适配，支持 600+ 开源模型即用</p>
-         </div>
-         <div class="verl-feature-card">
-            <div class="verl-feature-icon">🎯</div>
-            <h3>昇腾 NPU 支持</h3>
-            <p>深度适配华为昇腾设备，充分发挥国产芯片性能</p>
-         </div>
-      </div>
-
-      <!-- 开发者路径 -->
-      <div class="verl-path-wrapper">
-         <h2 style="text-align:center; color:var(--v-primary); margin-bottom:35px; border:none !important;">🎓 RL 后训练开发者学习路径</h2>
-         <div class="verl-path-container">
-            <div class="verl-path-step">
-               <span class="verl-step-num">1</span>
-               <h4>基础概念</h4>
-               <p>理解 RLHF, PPO/DPO 算法原理及奖励模型设计基础</p>
-            </div>
-            <div class="verl-path-step">
-               <span class="verl-step-num">2</span>
-               <h4>快速上手</h4>
-               <p>昇腾环境搭建、模型加载与基础微调单卡示例</p>
-            </div>
-            <div class="verl-path-step">
-               <span class="verl-step-num">3</span>
-               <h4>高级特性</h4>
-               <p>多卡分布式训练调优、性能瓶颈分析与自定义算法</p>
-            </div>
-            <div class="verl-path-step">
-               <span class="verl-step-num">4</span>
-               <h4>生产部署</h4>
-               <p>推理优化加速、模型评估基准与生产环境发布策略</p>
-            </div>
-         </div>
-      </div>
-
       <!-- 快速开始 -->
       <h2 class="verl-section-title">🚀 快速开始</h2>
       <div class="verl-quick-grid">
          <a href="../_generated/sources/verl/quick_start/ascend_quick_start.html" class="verl-quick-card">
-            <div style="font-size: 2rem;">📚</div>
+            <div class="verl-quick-card-icon">📚</div>
             <h4>快速入门</h4>
+            <p>昇腾环境搭建与基础训练示例</p>
          </a>
          <a href="../_generated/sources/verl/features/ascend_backend_features.html" class="verl-quick-card">
-            <div style="font-size: 2rem;">🔧</div>
+            <div class="verl-quick-card-icon">🔧</div>
             <h4>特性指南</h4>
+            <p>昇腾后端特性与一致性说明</p>
          </a>
          <a href="../_generated/sources/verl/examples/ascend_performance_analysis_guide.html" class="verl-quick-card">
-            <div style="font-size: 2rem;">⚙️</div>
+            <div class="verl-quick-card-icon">⚙️</div>
             <h4>应用实践</h4>
+            <p>性能分析与最佳实践案例</p>
          </a>
          <a href="../_generated/sources/verl/contribution_guide/ascend_ci_guide_zh.html" class="verl-quick-card">
-            <div style="font-size: 2rem;">👨‍💻</div>
+            <div class="verl-quick-card-icon">👨‍💻</div>
             <h4>开源开发</h4>
+            <p>CI 流程与贡献指南</p>
          </a>
       </div>
+
+      <!-- 核心特性（紧凑标签） -->
+      <div class="verl-features-compact">
+         <p class="verl-features-compact-title">✨ 核心特性</p>
+         <div class="verl-feature-tags">
+            <div class="verl-feature-tag"><span>🧬</span> 多样化 RL 算法</div>
+            <div class="verl-feature-tag"><span>🔗</span> 无缝框架集成</div>
+            <div class="verl-feature-tag"><span>📊</span> 灵活设备映射</div>
+            <div class="verl-feature-tag"><span>⚡</span> 业界领先吞吐量</div>
+            <div class="verl-feature-tag"><span>🤗</span> HuggingFace 集成</div>
+            <div class="verl-feature-tag"><span>🎯</span> 昇腾 NPU 支持</div>
+         </div>
+      </div>
    </div>
 
 ----
@@ -244,4 +181,4 @@ verl - 大模型强化学习训练框架
    :hidden:
    :caption: 🔧 开源开发
 
-   ../_generated/sources/verl/contribution_guide/ascend_ci_guide_zh
\ No newline at end of file
+   ../_generated/sources/verl/contribution_guide/ascend_ci_guide_zh

From 0e2a0ca0d46897ae35f8b352739bbc41275ce052 Mon Sep 17 00:00:00 2001
From: justbin-coder <jiazhibin48@gmail.com>
Date: Fri, 20 Mar 2026 14:51:46 +0800
Subject: [PATCH 3/3] fix(makefile): use .PHONY target for submodule init to
 fix empty dir skip issue

---
 Makefile | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Makefile b/Makefile
index 48efeeba..28f828c1 100644
--- a/Makefile
+++ b/Makefile
@@ -32,7 +32,7 @@ ONNXRUNTIME_CANN_MD_LOCAL := sources/_generated/sources/onnxruntime/quick_start.
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile copy-docs clean-submodules fetch-config sync-onnxruntime-doc
+.PHONY: help Makefile copy-docs clean-submodules fetch-config sync-onnxruntime-doc init-submodules
 
 # Fetch ascend config (always run to ensure freshness)
 .PHONY: $(ASCEND_CONFIG)
@@ -58,14 +58,13 @@ sync-onnxruntime-doc:
 	@rm -f "$(ONNXRUNTIME_CANN_MD_LOCAL).tmp"
 	@echo "Synced to $(ONNXRUNTIME_CANN_MD_LOCAL)"
 
-# Initialize submodules if not exists (use pinned commits for reproducibility)
-_repos/verl _repos/VeOmni _repos/LLaMA-Factory _repos/ms-swift:
-	@echo "Initializing submodules..."
+# Initialize submodules (always run to handle empty dirs left by git clone)
+init-submodules:
 	@git submodule sync --recursive
 	@git submodule update --init --remote
 
 # Copy documentation from submodules
-copy-docs: _repos/verl _repos/VeOmni _repos/LLaMA-Factory _repos/ms-swift
+copy-docs: init-submodules
 	@echo "Preparing generated docs directory..."
 	@mkdir -p $(GENERATED_DOCS)