[doc] add example doc to the website (#267)

Author: zhuzilin

.gitignore

@@ -188,4 +188,5 @@ local/
 .idea
 *.iml
 
-glm/
+glm/
+_examples_synced/

README.md

@@ -38,7 +38,7 @@
 ## Quick Start
 
 For a comprehensive quick start guide covering environment setup, data preparation, training startup, and key code analysis, please refer to:
-- [Quick Start Guide](./docs/en/quick_start.md)
+- [Quick Start Guide](./docs/en/get_started/quick_start.md)
 
 We also provides examples for some usecases not covered in the quick start guide, please check [examples](examples/).
 
@@ -50,7 +50,7 @@ Arguments in slime are divided into three categories:
 2.  **SGLang arguments**: All arguments for the installed SGLang are supported. These arguments must be prefixed with `--sglang-`. For example, `--mem-fraction-static` should be passed as `--sglang-mem-fraction-static`.
 3.  **slime-specific arguments**: Please refer to: [slime/utils/arguments.py](slime/utils/arguments.py)
 
-For complete usage instructions, please refer to the [Usage Documentation](docs/en/usage.md).
+For complete usage instructions, please refer to the [Usage Documentation](docs/en/get_started/usage.md).
 
 ## Developer Guide
 
@@ -63,9 +63,9 @@ For complete usage instructions, please refer to the [Usage Documentation](docs/
     pre-commit install
     ```
 
-  - For debugging tips, please refer to the [Debugging Guide](docs/en/debug.md)
+  - For debugging tips, please refer to the [Debugging Guide](docs/en/developer_guide/debug.md)
 
 ## FAQ & Acknowledgements
 
-  - For frequently asked questions, please see the [Q\&A](docs/en/qa.md)
+  - For frequently asked questions, please see the [Q\&A](docs/en/get_started/qa.md)
   - Special thanks to the following projects & communities: SGLang, Megatron‑LM, mbridge, OpenRLHF, veRL, Pai-Megatron-Patch and others.

README_zh.md

@@ -31,7 +31,7 @@
 
 有关环境配置、数据准备、训练启动和关键代码分析的完整快速开始指南，请参考：
 
-- [快速开始指南](./docs/zh/quick_start.md)
+- [快速开始指南](./docs/zh/get_started/quick_start.md)
 
 我还还额外提供了一些使用样例，请参考样例目录：[examples](examples/)。
 
@@ -43,7 +43,7 @@
 2. **sglang 参数**：支持环境中安装的 sglang 的所有参数，这些参数需要以 `--sglang` 起始，例如 `--mem-fraction-static` 需要通过 `--sglang-mem-fraction-static` 传入。
 3. **slime 自身的参数**：请见：[slime/utils/arguments.py](slime/utils/arguments.py)
 
-完整使用说明请查阅 [使用文档](docs/zh/usage.md)。
+完整使用说明请查阅 [使用文档](docs/zh/get_started/usage.md)。
 
 ## 开发指南
 
@@ -56,9 +56,9 @@
   pre-commit install
   ```
 
-- 调试技巧请参考 [debug 指南](docs/zh/debug.md)
+- 调试技巧请参考 [debug 指南](docs/zh/developer_guide/debug.md)
 
 ## 常见 Q&A 与致谢
 
-- 常见问题请见 [Q&A](docs/zh/qa.md)
+- 常见问题请见 [Q&A](docs/zh/get_started/qa.md)
 - 特别感谢以下项目 & 社区：SGLang、Megatron‑LM、mbridge、OpenRLHF、veRL、Pai-Megatron-Patch 等。

docs/conf.py

@@ -1,6 +1,8 @@
 import os
 import sys
 from datetime import datetime
+from pathlib import Path
+import shutil
 
 sys.path.insert(0, os.path.abspath("../.."))
 
@@ -130,8 +132,67 @@
 html_css_files = ["css/custom_log.css"]
 
 
+def _sync_examples(app):
+    """Sync top-level examples into language-specific doc trees.
+
+    Policy:
+      - README.md -> English docs/en/_examples_synced/<example>/README.md
+      - README_zh.md -> Chinese docs/zh/_examples_synced/<example>/README_zh.md
+      - If a language-specific README missing, that example is simply skipped for that language.
+    """
+    docs_root = Path(__file__).resolve().parent
+    src_dir = docs_root.parent / "examples"
+    if not src_dir.exists():
+        return
+
+    lang_cfgs = {
+        "en": {
+            "dir": docs_root / "en",
+            "readme_name": "README.md",
+            "title": "External Examples (Auto Synced)",
+            "note": "This section is auto-generated from repository examples/ by copying README.md of each example.",
+        },
+        "zh": {
+            "dir": docs_root / "zh",
+            # primary preferred name; will fallback to README.md
+            "readme_name": "README_zh.md",
+            "title": "外部示例 (自动同步)",
+            "note": "本节由构建时自动从仓库 examples/ 复制示例文档生成；优先使用 README_zh.md，若不存在则回退到 README.md。",
+        },
+    }
+
+    for lang, cfg in lang_cfgs.items():
+        lang_dir = cfg["dir"]
+        if not lang_dir.exists():
+            continue
+        out_dir = lang_dir / "_examples_synced"
+        if out_dir.exists():
+            shutil.rmtree(out_dir)
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        entries = []  # (example_name, readme_rel_path)
+        for d in sorted(src_dir.iterdir()):
+            if not d.is_dir():
+                continue
+            # language-specific selection with fallback for zh
+            if lang == "zh":
+                primary = d / cfg["readme_name"]  # README_zh.md
+                fallback = d / "README.md"
+                candidate = primary if primary.exists() else fallback
+            else:
+                candidate = d / cfg["readme_name"]
+            if not candidate.exists():
+                continue  # skip entirely if nothing suitable
+            target_dir = out_dir / d.name
+            target_dir.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(candidate, target_dir / "README.md")
+            entries.append((d.name, f"_examples_synced/{d.name}/README.md"))
+
+
 def setup(app):
     app.add_css_file("css/custom_log.css")
+    # ensure examples are synced before reading source files
+    app.connect("builder-inited", _sync_examples)
 
 
 myst_enable_extensions = [

docs/en/advanced/speculative-decoding.md

@@ -42,7 +42,7 @@ For details on parameter meanings and configuration, see the [SGLang speculative
   2. Specify a broader range for `--sglang-cuda-graph-bs` to avoid batch sizes that trigger CUDA graph padding.
   3. Disable CUDA graph (not recommended due to significant performance loss).
   4. **Notice:** Disabling CUDA graph padding with `--sglang-disable-cuda-graph-padding` is currently ineffective for speculative decoding. See [SGLang `cuda_graph_runner.py`](tbd).
-* For debugging, enable Slime’s `--debug-rollout-only` flag to isolate rollout behavior from parameter updates or model offloading.
+* For debugging, enable slime’s `--debug-rollout-only` flag to isolate rollout behavior from parameter updates or model offloading.
 
 ```bash
 # If speculative decoding fails, this can help debug

docs/en/examples/qwen3-4b-base-openhermes.md

@@ -1,4 +1,4 @@
-# SFT Qwen3-4B-Base with OpenHermes-2.5
+# SFT Qwen3-4B-Base
 
 
 ## Environment Preparation

docs/en/get_started/quick_start.md

@@ -7,8 +7,8 @@ This document will guide you through setting up the environment and getting star
 
 Since slime may contain temporary patches for sglang/megatron, to avoid potential environment configuration issues, we strongly recommend **users to use our latest Docker image**, which comes pre-configured with all dependencies.
 
-- For scenarios where Docker is not convenient, please refer to [build_conda.sh](./../../build_conda.sh);
-- For AMD support, please refer to [AMD Usage Tutorial](./amd_tutorial.md).
+- For scenarios where Docker is not convenient, please refer to [build_conda.sh](https://github.com/THUDM/slime/blob/main/build_conda.sh);
+- For AMD support, please refer to [AMD Usage Tutorial](../platform_support/amd_tutorial.md).
 
 ### Pull and Start Docker Container
 

docs/en/index.rst

@@ -39,7 +39,9 @@ slime is an LLM post-training framework for RL scaling, providing two core capab
    :caption: Other Usage
 
    examples/qwen3-4b-base-openhermes.md
-
+   _examples_synced/search-r1/README.md
+   _examples_synced/fully_async/README.md
+   _examples_synced/retool/README.md
 
 .. toctree::
    :maxdepth: 1

docs/en/platform_support/amd_tutorial.md

@@ -5,7 +5,7 @@
 
 ## Introduction
 
-If you are running Slime on AMD's Instinct, please refer to the following materials. This tutorial will explain how to set up the development environment (Docker), use the modified ROCm dependencies, and provide an example for running the experiments. The current rocm docker only support AMD's MI300 and MI325 GPUs.
+If you are running slime on AMD's Instinct, please refer to the following materials. This tutorial will explain how to set up the development environment (Docker), use the modified ROCm dependencies, and provide an example for running the experiments. The current rocm docker only support AMD's MI300 and MI325 GPUs.
 
 
 <!-- First, you need to configure the slime runtime environment according to the [Readme](../../README.md) documentation and cd to the slime project directory. -->

docs/zh/auto_examples.rst

@@ -0,0 +1,4 @@
+(构建时自动覆盖)
+===========================
+
+.. note:: 初次构建前此文件为占位；实际内容会在 Sphinx 构建阶段自动生成。