verl 文档系统构建指南从 Sphinx 源码到可浏览的 HTML 站点【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verlverlHybridFlow是一个面向大语言模型LLM后训练Post-Training的强化学习RL训练框架其官方文档位于仓库的docs/目录采用 Sphinx MyST reStructuredText 混合编写。本文基于仓库中的 docs/README.md 及配套构建配置完整讲解如何在本机把这份文档源码构建为 HTML 站点、如何本地预览并结合 docs/conf.py、docs/Makefile 等配置文件剖析构建系统的内部机制帮助你快速掌握 verl 文档的构建、阅读与二次编辑方法。一、文档仓库结构概览在开始构建之前先了解 verl 文档在仓库中的组织方式。文档全部位于docs/目录下入口文件为 docs/index.rst它通过多个toctree将分散的章节组织成完整的导航结构主要分区包括分区覆盖内容代表文件Quickstart安装、快速开始、多机部署docs/start/install.rst、docs/start/quickstart.rstProgramming guideHybridFlow 编程模型、单控制器接口docs/hybrid_flow.rst、docs/single_controller.rstData Preparation数据预处理与奖励函数编写docs/preparation/prepare_data.rstAlgorithmsPPO、GRPO、DAPO、SPPO 等算法讲解docs/algo/ppo.md、docs/algo/grpo.md 等PPO Trainer and WorkersRay Trainer、模型引擎、各 worker 说明docs/workers/ray_trainer.rst、docs/workers/sglang_worker.rstPerformance Tuning性能调优与 Profilingdocs/perf/best_practices.rst、docs/perf/verl_profiler_system.mdAPI References自动生成的 API 文档docs/api/single_controller.rst、docs/api/trainer.rstHardware Support多芯片Ascend、AMD支持docs/hardware/multi_chip_support.rst注意docs/目录中同时存在.rstreStructuredText与.mdMarkdown两种源文件Sphinx 通过source_suffix配置同时支持两者后文会详细说明。二、构建前的环境准备2.1 确保 verl 可被 Python 导入构建系统使用了 Sphinx 的autodoc扩展会从 verl 源码中自动提取 API 的 docstring 生成 API 参考文档例如 docs/api/single_controller.rst 中通过.. autoclass:: verl.single_controller.Worker自动生成类文档。因此如果需要渲染自动生成的 API docstring必须先让 verl 出现在 Python 的模块搜索路径中。官方推荐以可编辑模式安装 verl# 在仓库根目录执行-e 表示可编辑安装 pip install .. -e[test]安装后verl包即可被import verl正常导入。如果只是想查看不包含 API docstring 的纯静态文档也可以跳过这一步。2.2 安装文档构建依赖verl 的文档构建依赖全部声明在 docs/requirements-docs.txt 中内容如下# markdown support recommonmark myst_parser # markdown table support sphinx-markdown-tables # theme default rtd # crate-docs-theme sphinx-rtd-theme # pin tokenizers version to avoid env_logger version req tokenizers0.21安装命令pip install -r requirements-docs.txt各依赖的作用myst_parser与recommonmark为 Sphinx 提供 Markdown 解析能力。verl 文档大量使用.md文件如算法、性能调优章节没有这两个扩展Sphinx 将无法解析 Markdown 源文件。sphinx-markdown-tables支持在 Markdown 文档中书写表格语法如 docs/contributing/editing-agent-instructions.md 中的多张表格。sphinx-rtd-themeRead the Docs 风格主题即最终 HTML 站点的默认外观。tokenizers0.21固定 tokenizers 版本用于避免env_logger的版本需求冲突构建日志中的已知兼容性问题。三、构建 HTML 文档依赖安装完成后在docs/目录下依次执行两个命令即可完成构建make clean make htmlmake clean清空上一次构建的产物确保本次构建从干净状态开始避免陈旧文件干扰。make html调用 Sphinx 将全部源文件编译为 HTML 静态站点。构建完成后产物输出在docs/_build/html/目录下入口页面为docs/_build/html/index.html。3.1 Makefile 的机制docs/Makefile 是一个标准的最小化 Sphinx Makefile其核心定义如下SPHINXOPTS SPHINXBUILD sphinx-build SPHINXPROJ verl SOURCEDIR . BUILDDIR _buildSPHINXBUILD sphinx-build指定构建器为sphinx-build需与requirements-docs.txt中的依赖一起安装Sphinx 本身是其传递依赖。SOURCEDIR .源文件目录即docs/本身。BUILDDIR _build构建产物输出到docs/_build/。同时 Makefile 提供help目标make help可列出所有可用目标并将其他未知名目标统一路由到sphinx-build -M $这意味着make html、make latexpdf、make doctest等 Sphinx 标准目标都可以直接使用。3.2 conf.py 的关键配置解析构建行为的核心配置位于 docs/conf.py以下几个配置直接决定了最终站点的形态项目信息与主文档project verl copyright 2024 ByteDance Seed Foundation MLSys Team author Guangming Sheng, Chi Zhang, Yanghua Peng, Haibin Lin master_doc indexmaster_doc index指明入口文档为 docs/index.rst即前面介绍的 toctree 导航主文件。扩展与双格式支持extensions [ myst_parser, sphinx.ext.autodoc, sphinx.ext.autosummary, sphinx.ext.autosectionlabel, sphinx.ext.napoleon, sphinx.ext.viewcode, ] source_suffix { .rst: restructuredtext, .md: markdown, }myst_parser启用 Markdown 源文件解析且开启了dollarmath与amsmath扩展支持$...$、$$...$$数学公式语法verl 的算法文档中大量使用公式。sphinx.ext.autodoc/autosummary从 Python 源码自动提取 docstring 生成 API 文档。sphinx.ext.napoleon启用 Google 风格 docstring 解析napoleon_google_docstring True与 verl 源码的注释风格保持一致。sphinx.ext.viewcode在 API 文档页面提供查看源码链接方便读者跳转到对应实现。source_suffix字典同时声明.rst与.md两种后缀这是整个 docs 目录能混用两种格式的根本原因。主题与静态资源html_theme sphinx_rtd_theme html_static_path [_static] html_js_files [ js/runllm-widget.js, js/resizable-sidebar.js, ] html_css_files [custom.css]主题为sphinx_rtd_theme。额外加载两个自定义 JSdocs/_static/js/runllm-widget.js嵌入 RunLLM 对话机器人组件快捷键Modj唤起、docs/_static/js/resizable-sidebar.js侧边栏可拖拽调整宽度。自定义 CSS 位于 docs/_static/custom.css用于全宽布局调整。排除与告警抑制exclude_patterns [_build, Thumbs.db, .DS_Store] exclude_patterns [README.md, README_vllm0.7.md] suppress_warnings [ref.duplicate, ref.myst]值得注意docs/README.md本身被显式排除在构建范围之外因为它的定位是面向开发者的文档构建指南而非正式文档的一章但docs/README_vllm0.8.md等版本说明文件则被 docs/index.rst 引用进入导航Performance Tuning Guide 分区因此它不在排除列表中。四、本地预览构建产物构建完成后可以用 Python 内置的 HTTP 服务器在本地预览python -m http.server -d _build/html/启动后浏览器访问 http://localhost:8000 即可查看文档首页。两种查看方式对比方式命令/操作适用场景HTTP 服务器python -m http.server -d _build/html/浏览器访问http://localhost:8000本地完整预览支持相对路径导航推荐直接拖拽将_build/html/index.html拖入浏览器快速抽查单个页面但相对资源JS/CSS/图片加载可能受限五、构建失败排查与常见问题5.1 自动 API 文档为空或构建报错若构建时报autodoc无法导入verl.single_controller等模块说明 verl 尚未安装或不在 Python 路径中。回到 2.1 节执行pip install .. -e[test]安装后重新make clean make html。5.2 Markdown 语法未被解析确认已安装myst_parser且构建使用的 Python 环境中确实包含该包。可用pip show myst-parser验证。5.3 链接重复告警conf.py中通过suppress_warnings [ref.duplicate, ref.myst]抑制了重复标签引用告警若出现其他告警可查看_build/下的日志文件定位问题源文件。5.4 只想构建指定章节可以修改make html的调用通过SPHINXOPTS传入-D参数限制构建范围例如make html SPHINXOPTS-D master_docfaq/faq这会只构建 FAQ 章节docs/faq/faq.rst适合快速验证单个文件改动后的效果。六、从文档构建到文档协作verl 的文档体系不仅面向人类读者也面向 Agent。仓库根目录的 AGENTS.md 与 docs/contributing/editing-agent-instructions.md 共同维护了一套文档编写规范例如AGENTS.md应控制在 200 行以内、每个领域指南不超过 300 行、优先用示例而非大段文字等。当你计划为 verl 文档贡献新章节时建议先在本地完整构建一次pip install -r requirements-docs.txt→make clean make html确认当前基线可用在docs/下相应分区新增或修改.rst/.md文件若新增了文件在 docs/index.rst 的对应toctree中登记否则页面不会出现在导航中重新构建并本地预览检查新页面与链接是否正常。七、总结verl 的文档系统是一个典型的 Sphinx 多格式工程以 docs/index.rst 为导航骨架.rst与.md双格式共存通过autodoc从 verl 源码实时生成 API 参考。掌握安装依赖 →make clean make html→python -m http.server预览这条构建链路你就能随时把仓库中的最新文档编译为可浏览的 HTML 站点并在阅读与二次开发 verl 时快速查阅其完整的技术资料。【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 verl 文档系统构建指南：从 Sphinx 源码到可浏览的 HTML 站点
verl 文档系统构建指南从 Sphinx 源码到可浏览的 HTML 站点【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verlverlHybridFlow是一个面向大语言模型LLM后训练Post-Training的强化学习RL训练框架其官方文档位于仓库的docs/目录采用 Sphinx MyST reStructuredText 混合编写。本文基于仓库中的 docs/README.md 及配套构建配置完整讲解如何在本机把这份文档源码构建为 HTML 站点、如何本地预览并结合 docs/conf.py、docs/Makefile 等配置文件剖析构建系统的内部机制帮助你快速掌握 verl 文档的构建、阅读与二次编辑方法。一、文档仓库结构概览在开始构建之前先了解 verl 文档在仓库中的组织方式。文档全部位于docs/目录下入口文件为 docs/index.rst它通过多个toctree将分散的章节组织成完整的导航结构主要分区包括分区覆盖内容代表文件Quickstart安装、快速开始、多机部署docs/start/install.rst、docs/start/quickstart.rstProgramming guideHybridFlow 编程模型、单控制器接口docs/hybrid_flow.rst、docs/single_controller.rstData Preparation数据预处理与奖励函数编写docs/preparation/prepare_data.rstAlgorithmsPPO、GRPO、DAPO、SPPO 等算法讲解docs/algo/ppo.md、docs/algo/grpo.md 等PPO Trainer and WorkersRay Trainer、模型引擎、各 worker 说明docs/workers/ray_trainer.rst、docs/workers/sglang_worker.rstPerformance Tuning性能调优与 Profilingdocs/perf/best_practices.rst、docs/perf/verl_profiler_system.mdAPI References自动生成的 API 文档docs/api/single_controller.rst、docs/api/trainer.rstHardware Support多芯片Ascend、AMD支持docs/hardware/multi_chip_support.rst注意docs/目录中同时存在.rstreStructuredText与.mdMarkdown两种源文件Sphinx 通过source_suffix配置同时支持两者后文会详细说明。二、构建前的环境准备2.1 确保 verl 可被 Python 导入构建系统使用了 Sphinx 的autodoc扩展会从 verl 源码中自动提取 API 的 docstring 生成 API 参考文档例如 docs/api/single_controller.rst 中通过.. autoclass:: verl.single_controller.Worker自动生成类文档。因此如果需要渲染自动生成的 API docstring必须先让 verl 出现在 Python 的模块搜索路径中。官方推荐以可编辑模式安装 verl# 在仓库根目录执行-e 表示可编辑安装 pip install .. -e[test]安装后verl包即可被import verl正常导入。如果只是想查看不包含 API docstring 的纯静态文档也可以跳过这一步。2.2 安装文档构建依赖verl 的文档构建依赖全部声明在 docs/requirements-docs.txt 中内容如下# markdown support recommonmark myst_parser # markdown table support sphinx-markdown-tables # theme default rtd # crate-docs-theme sphinx-rtd-theme # pin tokenizers version to avoid env_logger version req tokenizers0.21安装命令pip install -r requirements-docs.txt各依赖的作用myst_parser与recommonmark为 Sphinx 提供 Markdown 解析能力。verl 文档大量使用.md文件如算法、性能调优章节没有这两个扩展Sphinx 将无法解析 Markdown 源文件。sphinx-markdown-tables支持在 Markdown 文档中书写表格语法如 docs/contributing/editing-agent-instructions.md 中的多张表格。sphinx-rtd-themeRead the Docs 风格主题即最终 HTML 站点的默认外观。tokenizers0.21固定 tokenizers 版本用于避免env_logger的版本需求冲突构建日志中的已知兼容性问题。三、构建 HTML 文档依赖安装完成后在docs/目录下依次执行两个命令即可完成构建make clean make htmlmake clean清空上一次构建的产物确保本次构建从干净状态开始避免陈旧文件干扰。make html调用 Sphinx 将全部源文件编译为 HTML 静态站点。构建完成后产物输出在docs/_build/html/目录下入口页面为docs/_build/html/index.html。3.1 Makefile 的机制docs/Makefile 是一个标准的最小化 Sphinx Makefile其核心定义如下SPHINXOPTS SPHINXBUILD sphinx-build SPHINXPROJ verl SOURCEDIR . BUILDDIR _buildSPHINXBUILD sphinx-build指定构建器为sphinx-build需与requirements-docs.txt中的依赖一起安装Sphinx 本身是其传递依赖。SOURCEDIR .源文件目录即docs/本身。BUILDDIR _build构建产物输出到docs/_build/。同时 Makefile 提供help目标make help可列出所有可用目标并将其他未知名目标统一路由到sphinx-build -M $这意味着make html、make latexpdf、make doctest等 Sphinx 标准目标都可以直接使用。3.2 conf.py 的关键配置解析构建行为的核心配置位于 docs/conf.py以下几个配置直接决定了最终站点的形态项目信息与主文档project verl copyright 2024 ByteDance Seed Foundation MLSys Team author Guangming Sheng, Chi Zhang, Yanghua Peng, Haibin Lin master_doc indexmaster_doc index指明入口文档为 docs/index.rst即前面介绍的 toctree 导航主文件。扩展与双格式支持extensions [ myst_parser, sphinx.ext.autodoc, sphinx.ext.autosummary, sphinx.ext.autosectionlabel, sphinx.ext.napoleon, sphinx.ext.viewcode, ] source_suffix { .rst: restructuredtext, .md: markdown, }myst_parser启用 Markdown 源文件解析且开启了dollarmath与amsmath扩展支持$...$、$$...$$数学公式语法verl 的算法文档中大量使用公式。sphinx.ext.autodoc/autosummary从 Python 源码自动提取 docstring 生成 API 文档。sphinx.ext.napoleon启用 Google 风格 docstring 解析napoleon_google_docstring True与 verl 源码的注释风格保持一致。sphinx.ext.viewcode在 API 文档页面提供查看源码链接方便读者跳转到对应实现。source_suffix字典同时声明.rst与.md两种后缀这是整个 docs 目录能混用两种格式的根本原因。主题与静态资源html_theme sphinx_rtd_theme html_static_path [_static] html_js_files [ js/runllm-widget.js, js/resizable-sidebar.js, ] html_css_files [custom.css]主题为sphinx_rtd_theme。额外加载两个自定义 JSdocs/_static/js/runllm-widget.js嵌入 RunLLM 对话机器人组件快捷键Modj唤起、docs/_static/js/resizable-sidebar.js侧边栏可拖拽调整宽度。自定义 CSS 位于 docs/_static/custom.css用于全宽布局调整。排除与告警抑制exclude_patterns [_build, Thumbs.db, .DS_Store] exclude_patterns [README.md, README_vllm0.7.md] suppress_warnings [ref.duplicate, ref.myst]值得注意docs/README.md本身被显式排除在构建范围之外因为它的定位是面向开发者的文档构建指南而非正式文档的一章但docs/README_vllm0.8.md等版本说明文件则被 docs/index.rst 引用进入导航Performance Tuning Guide 分区因此它不在排除列表中。四、本地预览构建产物构建完成后可以用 Python 内置的 HTTP 服务器在本地预览python -m http.server -d _build/html/启动后浏览器访问 http://localhost:8000 即可查看文档首页。两种查看方式对比方式命令/操作适用场景HTTP 服务器python -m http.server -d _build/html/浏览器访问http://localhost:8000本地完整预览支持相对路径导航推荐直接拖拽将_build/html/index.html拖入浏览器快速抽查单个页面但相对资源JS/CSS/图片加载可能受限五、构建失败排查与常见问题5.1 自动 API 文档为空或构建报错若构建时报autodoc无法导入verl.single_controller等模块说明 verl 尚未安装或不在 Python 路径中。回到 2.1 节执行pip install .. -e[test]安装后重新make clean make html。5.2 Markdown 语法未被解析确认已安装myst_parser且构建使用的 Python 环境中确实包含该包。可用pip show myst-parser验证。5.3 链接重复告警conf.py中通过suppress_warnings [ref.duplicate, ref.myst]抑制了重复标签引用告警若出现其他告警可查看_build/下的日志文件定位问题源文件。5.4 只想构建指定章节可以修改make html的调用通过SPHINXOPTS传入-D参数限制构建范围例如make html SPHINXOPTS-D master_docfaq/faq这会只构建 FAQ 章节docs/faq/faq.rst适合快速验证单个文件改动后的效果。六、从文档构建到文档协作verl 的文档体系不仅面向人类读者也面向 Agent。仓库根目录的 AGENTS.md 与 docs/contributing/editing-agent-instructions.md 共同维护了一套文档编写规范例如AGENTS.md应控制在 200 行以内、每个领域指南不超过 300 行、优先用示例而非大段文字等。当你计划为 verl 文档贡献新章节时建议先在本地完整构建一次pip install -r requirements-docs.txt→make clean make html确认当前基线可用在docs/下相应分区新增或修改.rst/.md文件若新增了文件在 docs/index.rst 的对应toctree中登记否则页面不会出现在导航中重新构建并本地预览检查新页面与链接是否正常。七、总结verl 的文档系统是一个典型的 Sphinx 多格式工程以 docs/index.rst 为导航骨架.rst与.md双格式共存通过autodoc从 verl 源码实时生成 API 参考。掌握安装依赖 →make clean make html→python -m http.server预览这条构建链路你就能随时把仓库中的最新文档编译为可浏览的 HTML 站点并在阅读与二次开发 verl 时快速查阅其完整的技术资料。【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考