Bulid the mkdocs of Tutorial successfully (#563)

Author: chenzhex

.github/workflows/deploy_doc.yml

@@ -25,6 +25,8 @@ jobs:
         run: |
           git submodule init LazyLLM-Env
           git submodule update LazyLLM-Env
+          git submodule init Tutorial
+          git submodule update Tutorial
 
       - name: Set up python
         uses: actions/setup-python@v5
@@ -39,6 +41,8 @@ jobs:
           cp -r docs/assets docs/zh
           cp -r docs/assets docs/en
           python docs/add_docstrings.py
+          python docs/link_assets.py
+          python docs/ipynb2md.py
           python docs/gen_mkdocs_yaml.py
 
       - name: Start MkDocs server

.readthedocs.yaml

@@ -8,9 +8,12 @@ build:
     pre_build:
       - pip install -r requirements.txt
       - pip install -r docs/requirements.txt
+      - git submodule update --init --recursive
       - cp -r docs/assets docs/zh
       - cp -r docs/assets docs/en
       - python docs/add_docstrings.py
+      - python docs/link_assets.py
+      - python docs/ipynb2md.py 2>&1 | tee -a build.log
       - python docs/gen_mkdocs_yaml.py
 
 python:
@@ -19,4 +22,3 @@ python:
 
 mkdocs:
   configuration: mkdocs.yml
-

Tutorial

@@ -0,0 +1,64 @@
+import nbformat
+import re
+import os
+import glob
+import logging
+from pathlib import Path
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s")
+logger = logging.getLogger(__name__)
+
+# Regex pattern to replace: <source src="./xxx"> → <source src="../xxx">
+VIDEO_SRC_PATTERN = re.compile(r'(<source\s+src=")\./([^"]+)(")')
+script_dir = os.path.dirname(os.path.abspath(__file__))
+
+
+def convert_ipynb_to_md(ipynb_path: str, output_dir: str):
+    """
+    Convert a Jupyter notebook to Markdown, replacing video src paths.
+
+    Args:
+        ipynb_path (str): Path to the input .ipynb file.
+        output_dir (str): Directory to save the converted .md file.
+    """
+    ipynb_path = Path(ipynb_path)
+    notebook_name = ipynb_path.stem
+    output_dir = Path(output_dir)
+    md_path = output_dir / f"{notebook_name}.md"
+    os.makedirs(md_path.parent, exist_ok=True)
+
+    with open(ipynb_path, "r", encoding="utf-8") as f:
+        nb = nbformat.read(f, as_version=4)
+
+    md_lines = []
+
+    for cell in nb.cells:
+        if cell.cell_type == "markdown":
+            text = cell.source
+            # Replace video source path from ./ to ../
+            text = VIDEO_SRC_PATTERN.sub(r'\1../\2\3', text)
+            md_lines.append(text)
+        elif cell.cell_type == "code":
+            if cell.get("source"):
+                md_lines.append(f"```python\n{cell.source}\n```")
+
+    with open(md_path, "w", encoding="utf-8") as f:
+        f.write("\n\n".join(md_lines))
+
+    # Try to get relative path for logging; fallback to filename if error occurs
+    try:
+        relative_md_path = md_path.relative_to(Path.cwd())
+    except ValueError:
+        relative_md_path = md_path.name
+
+    logger.info(f"✅ Converted: {ipynb_path.name} → {relative_md_path}")
+
+
+if __name__ == "__main__":
+    # Batch convert all notebooks matching the pattern
+    input_files = glob.glob("Tutorial/rag/notebook/chapter*/*.ipynb", recursive=True)
+    output_dir = os.path.join(script_dir, "zh/Tutorial")
+
+    for ipynb_file in input_files:
+        convert_ipynb_to_md(ipynb_file, output_dir)

docs/ipynb2md.py

@@ -0,0 +1,46 @@
+import os
+import glob
+import shutil
+from pathlib import Path
+from itertools import chain
+
+
+def link_assets():
+    """
+    Create symbolic links in docs/zh/Tutorial pointing to the actual
+    {videos, images} directories found under Tutorial/rag/notebook/chapter*/.
+    Each link will be named after the basename of the original directory.
+    """
+    dest_dir = Path("docs/zh/Tutorial")
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    # Manually expand the {videos,images} part
+    patterns = [
+        "Tutorial/rag/notebook/chapter*/*_videos",
+        "Tutorial/rag/notebook/chapter*/*_images",
+    ]
+    paths = list(chain.from_iterable(glob.glob(p, recursive=True) for p in patterns))
+
+    for path_str in paths:
+        path = Path(path_str)
+        if not path.exists():
+            continue
+
+        name = path.name
+        target = path.resolve()
+        link_path = dest_dir / name
+
+        try:
+            if link_path.exists():
+                if link_path.is_symlink() or link_path.is_file():
+                    link_path.unlink()
+                elif link_path.is_dir():
+                    shutil.rmtree(link_path)
+            os.symlink(target, link_path)
+            print(f"✅ Linked {link_path} → {target}")
+        except Exception as e:
+            print(f"❌ Failed to link {link_path} → {target}: {e}")
+
+
+if __name__ == "__main__":
+    link_assets()

docs/link_assets.py

@@ -32,6 +32,27 @@ nav:
   - Flow: API Reference/flow.md
   - Module: API Reference/module.md
   - Tools: API Reference/tools.md
+- Tutorials:
+  - Overview: Tutorial/index.md
+  - Lesson 1: Tutorial/1.md
+  - Lesson 2: Tutorial/2.md
+  - Lesson 3: Tutorial/3.md
+  - Lesson 4: Tutorial/4.md
+  - Lesson 5: Tutorial/5.md
+  - Lesson 6: Tutorial/6.md
+  - Lesson 7: Tutorial/7.md
+  - Lesson 8: Tutorial/8.md
+  - Lesson 9: Tutorial/9.md
+  - Lesson 10: Tutorial/10.md
+  - Lesson 11: Tutorial/11.md
+  - Lesson 12: Tutorial/12.md
+  - Lesson 13: Tutorial/13.md
+  - Lesson 14: Tutorial/14.md
+  - Lesson 15: Tutorial/15.md
+  - Lesson 16: Tutorial/16.md
+  - Lesson 17: Tutorial/17.md
+  - Lesson 18: Tutorial/18.md
+  - Lesson 19: Tutorial/19.md
 theme:
   language: en
   name: material

docs/mkdocs.template.yml

@@ -29,3 +29,4 @@ redis
 funasr
 transformers
 ChatTTS
+nbformat

docs/requirements.txt

@@ -0,0 +1,68 @@
+# 教程概览
+
+欢迎来到 LazyLLM 教程！
+
+本教程旨在帮助你快速上手和深入了解 LazyLLM 的各项功能。
+
+## 教程目录
+
+- [第1讲 RAG原理解读：让检索增强生成不再是黑盒](1.md)  
+  透彻讲解 RAG（Retrieval-Augmented Generation）的原理与结构。
+
+- [第2讲 10分钟上手一个最小可用RAG系统](2.md)  
+  零基础快速构建最小可运行的 RAG 系统。
+
+- [第3讲 大模型怎么玩：用LazyLLM带你理解调用逻辑与Prompt魔法](3.md)  
+  深入理解大模型的调用过程与 Prompt 的组织方式。
+
+- [第4讲 RAG项目工程化入门：从脚本走向模块化与可维护性](4.md)  
+  教你如何将 RAG 项目逐步工程化，提升可维护性。
+
+- [第5讲 打造专属Reader组件：轻松解析HTML、PDF等复杂文档格式](5.md)  
+  自定义文档解析器，实现对多种文档格式的支持。
+
+- [第6讲 检索更准：RAG召回效果优化的底层逻辑与技巧](6.md)  
+  学习影响召回效果的核心要素与优化策略。
+
+- [第7讲 检索升级实践：亲手打造“更聪明”的文档理解系统！](7.md)  
+  实战提升系统对复杂文档的理解能力。
+
+- [第8讲 不止是cosine！匹配策略决定你召回的质量](8.md)  
+  多种向量匹配策略的对比与应用分析。
+
+- [第9讲 微调实践：让大模型和向量模型更懂你的领域](9.md)  
+  基于私有领域数据对 Embedding 与 LLM 进行微调。
+
+- [第10讲 探索Deepseek：打造思维能力更强的RAG系统](10.md)  
+  集成 DeepSeek 等强模型提升多步推理能力。
+
+- [第11讲 性能优化指南：从冷启动到响应加速你的RAG](11.md)  
+  全方位介绍 RAG 系统的启动与响应性能优化技巧。
+
+- [第12讲 实践：用缓存、异步与向量引擎加速你的RAG](12.md)  
+  手把手教你使用缓存、异步处理、引擎插件等方式提速。
+
+- [第13讲 RAG+多模态：图片、表格通吃的问答系统](13.md)  
+  构建支持图文混合理解的多模态 RAG 系统。
+
+- [第14讲 实战：构建一个支持复杂学术论文问答的RAG系统](14.md)  
+  面向论文场景，搭建具备上下文、结构感知能力的系统。
+
+- [第15讲 大视角问答：RAG如何支持跨文档、跨维度总结](15.md)  
+  实现多文档总结与维度整合型问答。
+
+- [第16讲 实践：打造具备宏观问答与图表生成功能的论文问答的RAG系统](16.md)  
+  加入宏观总结与图表生成，提升问答系统交互质量。
+
+- [第17讲 企业级RAG：权限、共享与内容安全的全链路方案](17.md)  
+  企业内部部署场景下的权限管理与安全设计实战。
+
+- [第18讲 高阶RAG：Agentic RAG](18.md)  
+  探索 Agent + RAG 的融合方式，增强任务执行能力。
+
+- [第19讲： RAG × 知识图谱：从关系结构中召回更准确的内容](19.md)  
+  打通结构化知识图谱与生成式问答系统的协同路径。
+
+---
+
+准备好开始探索了吗？点击任意一讲，即可深入学习 🚀