构建与维护 LeRobot 文档站点doc-builder 构建、预览与导航编排完整指南【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot本文是 LeRobot 仓库文档维护者的实操手册讲解如何基于 Hugging Face 官方的doc-builder工具链在本地构建、预览并维护docs/source/下的整套文档站点。你将掌握从安装构建依赖、生成 MDX 页面、本地热预览到新增导航条目、安全重命名章节、以及遵循仓库统一 docstring 写作规范的全流程让文档贡献从改一个 .mdx 文件完整走通到在浏览器里看到渲染结果。本文以 docs/README.md 为骨架展开并结合 docs-requirements.txt、docs/source/_toctree.yml、Makefile 与 docs/source/writing_docstrings.mdx 等仓库实际文件补充实现细节。一、构建文档前的准备工作LeRobot 的文档站点采用 Hugging Face 的doc-builder从docs/source/目录中的 Markdown/MDX 源文件渲染生成。在开始构建之前需要先安装构建文档所需的全部 Python 包在代码仓库根目录执行pip install -e . -r docs-requirements.txt这条命令做了两件事-e .以可编辑模式安装当前仓库即 LeRobot 本体及其依赖-r docs-requirements.txt安装文档构建相关的额外依赖。查看仓库根目录下的 docs-requirements.txt其内容非常简单# docs-requirements.txt hf-doc-builder githttps://github.com/huggingface/doc-builder.gitmain watchdog6.0.0即构建文档所需的核心工具链只有两个组件hf-doc-builder从main分支直接安装的 doc-builder 本体提供doc-builder build/doc-builder preview两个 CLI 入口负责将.md/.mdx源文件渲染成网站页面同时负责解析[[autodoc]]之类的自动文档指令watchdog文件系统监听库供doc-builder preview在本地文件变更时自动刷新预览页面使用下文预览章节会再次用到它。此外构建还要求本机安装Node.js。doc-builder在渲染过程中会依赖 Node.js 生态完成部分前端构建工作因此请先确保node命令可用再继续后续步骤。注意只有在你计划修改文档、并希望在提交之前于本地检查渲染效果时才需要构建文档。构建产物MDX 文件等属于临时文件不需要也不应该git commit到仓库中——提交构建产物只会污染仓库、制造不必要的合并冲突。二、构建文档生成可渲染的 MDX 页面安装好doc-builder及附加依赖后即可在仓库根目录执行构建命令doc-builder build lerobot docs/source/ --build_dir /tmp/lerobot-doc-build各参数含义如下参数含义lerobot库名对应pyproject.toml/setup.py中定义的包名doc-builder 用它定位项目元信息docs/source/文档源文件目录即 docs/source 下所有.mdx/.md文件--build_dir构建输出目录可自由指定为任意临时文件夹命令会自动创建该目录构建完成后--build_dir指定的目录下会生成一系列MDX 文件这些文件就是最终渲染在官网文档页面上的内容。你可以用任意 Markdown 编辑器打开检查排版与链接是否正确。构建命令本身还承担一项重要的契约校验[[autodoc]]若指向不存在的对象会直接导致文档构建失败详见 docs/source/writing_docstrings.mdx 的检查清单因此它也是提交文档前最便宜的烟雾测试。三、本地预览文档http://localhost:3000构建只能生成静态页面若要像访问官网一样交互式浏览可以使用doc-builder preview启动本地开发服务器。首次预览前先安装文件监听依赖pip install watchdog然后运行doc-builder preview lerobot docs/source/启动后文档站点会在本地端口渲染通过浏览器访问 http://localhost:3000 即可预览。watchdog会监听docs/source/下的文件变更编辑保存后页面自动刷新非常适合边改边看。如果你已经提交了 Pull Request也可以在 PR 评论区找到机器人自动生成的一份文档预览链接无需本地启动即可审阅变更效果。注意preview命令只对已经存在的文档文件生效。当你新增了一个全新的文件时必须先把它登记到 docs/source/_toctree.yml 中然后用ctrl-c停止当前preview进程并重新执行doc-builder preview ...新页面才会出现在导航与路由中。四、新增导航栏元素与教程两步走LeRobot 文档站点的左侧导航完全由 docs/source/_toctree.yml 这一个文件驱动。该文件按sections分组每组包含一个title与若干local/title条目例如- sections: - local: index title: LeRobot - local: installation title: Installation - local: cheat-sheet title: Cheat sheet title: Get started其中local是不带扩展名的文件名title是侧边栏显示的名称。仓库现有导航按主题组织为十余个分组Get started、Tutorials、Compute Hardware、Datasets、Policies、Reward Models、Inference、Simulation、Benchmarks、Robot Processors、Robots、Teleoperators、Sensors、Resources、About以及末端的 API Reference指向 docs/source/api 下各接口页面。新增一个导航元素或一篇新教程本质上是同一个两步流程新建源文件在docs/source/目录下创建.mdMarkdown或.mdx文件登记到 toc-tree在 docs/source/_toctree.yml 中对应分组下追加一条记录local填文件名去掉扩展名、title填导航显示名。需要注意接受的文件格式是 Markdown.md.mdx同样被仓库广泛使用见docs/source/下大量.mdx文件。新文件务必放在语义正确的分组下拿不准归属时可以开一个 GitHub Issue 或在 PR 中说明让维护者确认放置位置。五、重命名章节与移动内容保住旧锚点链接文档是长生命周期的资产——一个章节的链接可能已经散落在 Issue、论坛、社交媒体中被大量引用。当你重命名章节标题如把 Section A 改为 Section B或把某章节从一个文档移动到另一个文档时数月后仍会有读者通过旧链接导航。因此 LeRobot 文档约定在移动/重命名发生时于原位置保留一张章节去向地图并保持原始 anchor 不变。5.1 在同一文档内重命名若章节从 Section A 重命名为 Section B在原文件末尾追加如下片段保留旧的 anchorsection-a指向新的section-bSections that were moved: [ a href#section-bSection A/aa idsection-a/a ]这样旧链接#section-a依然能跳转到同一页面内对应位置。5.2 移动到另一个文档若章节被移动到了其他文件则在原文件末尾记录目标文件同时仍保留旧 anchorSections that were moved: [ a href../new-file#section-bSection A/aa idsection-a/a ]这里的关键约定是使用相对路径relative style链接到新文件而非绝对路径或版本化 URL——这样在不同版本的文档versioned docs中继续可用不会因版本目录层级变化而失效。仓库为这种丰富移动段落提供了现成范例可以参考 transformers 的 Trainer 文档末尾的 moved sections 集合其维护方式与 LeRobot 完全一致。从 docs/source/_toctree.yml 的演进历史也可以看到LeRobot 大量文档经历过重命名重组如多份policy_*.md/policy_*_README.md并存于 docs/source锚点保留策略正是为这类持续重组兜底。六、编写源码文档格式规范与图片策略6.1 代码与参数格式文档正文中需要以代码形式呈现的值参数名、True、None或任意字符串字面量应使用反引号包裹例如like so。多行代码块使用 Markdown 标准的两个三反引号围栏包裹 # first line of code # second line # etc 6.2 图片策略优先引用托管数据集杜绝大文件入库由于仓库快速膨胀LeRobot 明确要求不要向仓库提交会显著增加体积的文件——包括图片、视频及其他非文本文件。正确的做法是将图片上传到hf.co托管的 dataset例如hf-internal-testing系列或huggingface/documentation-images这类官方文档图片数据集然后在文档中以 URL 方式引用。外部贡献者可以先把图片随 PR 提交再请 Hugging Face 成员协助迁移到该数据集。这也是为什么 docs/source/index.mdx 等页面中的配图一律使用外部托管 URL而不是仓库内相对路径的二进制文件。6.3 文档写作的硬规范docstring 即 API 文档值得强调的是LeRobot 的 API 参考页面直接从src/lerobot/下的 docstring 生成因此写文档不只是写docs/source/下的.mdx更核心的是遵守 docs/source/writing_docstrings.mdx 中定义的 docstring 契约。该契约由 doc-builder 渲染器和 CI 检查共同强制要点包括章节顺序固定Args:→Returns:→Raises:→Yields:→Example:→Note:先一句话摘要再自由描述最后才是各节Args:行是机器解析的格式为name (type, *optional*, defaults to X)其中defaults to子句会被 utils/check_docstrings.py 与真实签名比对写错默认值 CI 直接失败属性用**Attributes**:而非Attributes:后者会被 doc-builder 误解析为构造参数的同义词导致属性被渲染成参数交叉引用用方括号反引号语法如[~Robot.connect]不支持 Sphinx 角色:pymeth:等示例必须放在 fenced 代码块内并包含提示符触及硬件、GPU 或 Hub 下载的示例一律加# doctest: SKIP。6.4 文档质量的自动化关卡docstring 与文档的质量由多层检查保障全部可在 Makefile 中一键触发检查命令作用make check-docstrings运行 utils/check_docstrings.py 与check_config_docstrings.py校验Args:条目与签名一致、文档化默认值与真实默认值未漂移make doctest执行 utils/documentation_tests.txt 白名单文件中 docstring 示例确保示例仍然可运行make check-doctest-list校验documentation_tests.txt中条目未过期且按字母排序make fix-docstrings自动改写不匹配的Args:块并插入fill_docstring占位符再由人工补全从 utils/check_docstrings.py 的源码可以看到其MODULES_TO_CHECK列表当前含lerobot.robots是棘轮机制模块的 docstring 规范转换完成后才被纳入检查范围而OBJECTS_TO_IGNORE则暂时豁免尚未完成转换的对象。这种渐进式收紧策略让 CI 从第一天起就能保持绿色。提交 PR 前的标准自检命令组合是make check-docstrings make doctest pre-commit run --all-files跑完后用doc-builder build渲染一遍页面并亲眼检查最终效果The rendered page has been eyeballed 是 checklist 的最后一条。七、维护者速查清单依赖安装pip install -e . -r docs-requirements.txt外加 Node.js本地构建doc-builder build lerobot docs/source/ --build_dir 临时目录本地预览pip install watchdog后执行doc-builder preview lerobot docs/source/访问 http://localhost:3000新增文件创建.md/.mdx源文件 → 登记到 docs/source/_toctree.yml → 重启preview重命名/移动章节在原位置保留a id旧anchor映射目标用相对路径图片优先放 hf.co 托管数据集避免仓库内新增大体积二进制文件提交前make check-docstrings make doctest pre-commit run --all-files并本地构建目验渲染结果。遵循这套流程你就能与 LeRobot 仓库的文档 CI 保持完全同步任何 docstring 或.mdx变更都能安全、规范地落地到站点上。【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
构建与维护 LeRobot 文档站点：doc-builder 构建、预览与导航编排完整指南
构建与维护 LeRobot 文档站点doc-builder 构建、预览与导航编排完整指南【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot本文是 LeRobot 仓库文档维护者的实操手册讲解如何基于 Hugging Face 官方的doc-builder工具链在本地构建、预览并维护docs/source/下的整套文档站点。你将掌握从安装构建依赖、生成 MDX 页面、本地热预览到新增导航条目、安全重命名章节、以及遵循仓库统一 docstring 写作规范的全流程让文档贡献从改一个 .mdx 文件完整走通到在浏览器里看到渲染结果。本文以 docs/README.md 为骨架展开并结合 docs-requirements.txt、docs/source/_toctree.yml、Makefile 与 docs/source/writing_docstrings.mdx 等仓库实际文件补充实现细节。一、构建文档前的准备工作LeRobot 的文档站点采用 Hugging Face 的doc-builder从docs/source/目录中的 Markdown/MDX 源文件渲染生成。在开始构建之前需要先安装构建文档所需的全部 Python 包在代码仓库根目录执行pip install -e . -r docs-requirements.txt这条命令做了两件事-e .以可编辑模式安装当前仓库即 LeRobot 本体及其依赖-r docs-requirements.txt安装文档构建相关的额外依赖。查看仓库根目录下的 docs-requirements.txt其内容非常简单# docs-requirements.txt hf-doc-builder githttps://github.com/huggingface/doc-builder.gitmain watchdog6.0.0即构建文档所需的核心工具链只有两个组件hf-doc-builder从main分支直接安装的 doc-builder 本体提供doc-builder build/doc-builder preview两个 CLI 入口负责将.md/.mdx源文件渲染成网站页面同时负责解析[[autodoc]]之类的自动文档指令watchdog文件系统监听库供doc-builder preview在本地文件变更时自动刷新预览页面使用下文预览章节会再次用到它。此外构建还要求本机安装Node.js。doc-builder在渲染过程中会依赖 Node.js 生态完成部分前端构建工作因此请先确保node命令可用再继续后续步骤。注意只有在你计划修改文档、并希望在提交之前于本地检查渲染效果时才需要构建文档。构建产物MDX 文件等属于临时文件不需要也不应该git commit到仓库中——提交构建产物只会污染仓库、制造不必要的合并冲突。二、构建文档生成可渲染的 MDX 页面安装好doc-builder及附加依赖后即可在仓库根目录执行构建命令doc-builder build lerobot docs/source/ --build_dir /tmp/lerobot-doc-build各参数含义如下参数含义lerobot库名对应pyproject.toml/setup.py中定义的包名doc-builder 用它定位项目元信息docs/source/文档源文件目录即 docs/source 下所有.mdx/.md文件--build_dir构建输出目录可自由指定为任意临时文件夹命令会自动创建该目录构建完成后--build_dir指定的目录下会生成一系列MDX 文件这些文件就是最终渲染在官网文档页面上的内容。你可以用任意 Markdown 编辑器打开检查排版与链接是否正确。构建命令本身还承担一项重要的契约校验[[autodoc]]若指向不存在的对象会直接导致文档构建失败详见 docs/source/writing_docstrings.mdx 的检查清单因此它也是提交文档前最便宜的烟雾测试。三、本地预览文档http://localhost:3000构建只能生成静态页面若要像访问官网一样交互式浏览可以使用doc-builder preview启动本地开发服务器。首次预览前先安装文件监听依赖pip install watchdog然后运行doc-builder preview lerobot docs/source/启动后文档站点会在本地端口渲染通过浏览器访问 http://localhost:3000 即可预览。watchdog会监听docs/source/下的文件变更编辑保存后页面自动刷新非常适合边改边看。如果你已经提交了 Pull Request也可以在 PR 评论区找到机器人自动生成的一份文档预览链接无需本地启动即可审阅变更效果。注意preview命令只对已经存在的文档文件生效。当你新增了一个全新的文件时必须先把它登记到 docs/source/_toctree.yml 中然后用ctrl-c停止当前preview进程并重新执行doc-builder preview ...新页面才会出现在导航与路由中。四、新增导航栏元素与教程两步走LeRobot 文档站点的左侧导航完全由 docs/source/_toctree.yml 这一个文件驱动。该文件按sections分组每组包含一个title与若干local/title条目例如- sections: - local: index title: LeRobot - local: installation title: Installation - local: cheat-sheet title: Cheat sheet title: Get started其中local是不带扩展名的文件名title是侧边栏显示的名称。仓库现有导航按主题组织为十余个分组Get started、Tutorials、Compute Hardware、Datasets、Policies、Reward Models、Inference、Simulation、Benchmarks、Robot Processors、Robots、Teleoperators、Sensors、Resources、About以及末端的 API Reference指向 docs/source/api 下各接口页面。新增一个导航元素或一篇新教程本质上是同一个两步流程新建源文件在docs/source/目录下创建.mdMarkdown或.mdx文件登记到 toc-tree在 docs/source/_toctree.yml 中对应分组下追加一条记录local填文件名去掉扩展名、title填导航显示名。需要注意接受的文件格式是 Markdown.md.mdx同样被仓库广泛使用见docs/source/下大量.mdx文件。新文件务必放在语义正确的分组下拿不准归属时可以开一个 GitHub Issue 或在 PR 中说明让维护者确认放置位置。五、重命名章节与移动内容保住旧锚点链接文档是长生命周期的资产——一个章节的链接可能已经散落在 Issue、论坛、社交媒体中被大量引用。当你重命名章节标题如把 Section A 改为 Section B或把某章节从一个文档移动到另一个文档时数月后仍会有读者通过旧链接导航。因此 LeRobot 文档约定在移动/重命名发生时于原位置保留一张章节去向地图并保持原始 anchor 不变。5.1 在同一文档内重命名若章节从 Section A 重命名为 Section B在原文件末尾追加如下片段保留旧的 anchorsection-a指向新的section-bSections that were moved: [ a href#section-bSection A/aa idsection-a/a ]这样旧链接#section-a依然能跳转到同一页面内对应位置。5.2 移动到另一个文档若章节被移动到了其他文件则在原文件末尾记录目标文件同时仍保留旧 anchorSections that were moved: [ a href../new-file#section-bSection A/aa idsection-a/a ]这里的关键约定是使用相对路径relative style链接到新文件而非绝对路径或版本化 URL——这样在不同版本的文档versioned docs中继续可用不会因版本目录层级变化而失效。仓库为这种丰富移动段落提供了现成范例可以参考 transformers 的 Trainer 文档末尾的 moved sections 集合其维护方式与 LeRobot 完全一致。从 docs/source/_toctree.yml 的演进历史也可以看到LeRobot 大量文档经历过重命名重组如多份policy_*.md/policy_*_README.md并存于 docs/source锚点保留策略正是为这类持续重组兜底。六、编写源码文档格式规范与图片策略6.1 代码与参数格式文档正文中需要以代码形式呈现的值参数名、True、None或任意字符串字面量应使用反引号包裹例如like so。多行代码块使用 Markdown 标准的两个三反引号围栏包裹 # first line of code # second line # etc 6.2 图片策略优先引用托管数据集杜绝大文件入库由于仓库快速膨胀LeRobot 明确要求不要向仓库提交会显著增加体积的文件——包括图片、视频及其他非文本文件。正确的做法是将图片上传到hf.co托管的 dataset例如hf-internal-testing系列或huggingface/documentation-images这类官方文档图片数据集然后在文档中以 URL 方式引用。外部贡献者可以先把图片随 PR 提交再请 Hugging Face 成员协助迁移到该数据集。这也是为什么 docs/source/index.mdx 等页面中的配图一律使用外部托管 URL而不是仓库内相对路径的二进制文件。6.3 文档写作的硬规范docstring 即 API 文档值得强调的是LeRobot 的 API 参考页面直接从src/lerobot/下的 docstring 生成因此写文档不只是写docs/source/下的.mdx更核心的是遵守 docs/source/writing_docstrings.mdx 中定义的 docstring 契约。该契约由 doc-builder 渲染器和 CI 检查共同强制要点包括章节顺序固定Args:→Returns:→Raises:→Yields:→Example:→Note:先一句话摘要再自由描述最后才是各节Args:行是机器解析的格式为name (type, *optional*, defaults to X)其中defaults to子句会被 utils/check_docstrings.py 与真实签名比对写错默认值 CI 直接失败属性用**Attributes**:而非Attributes:后者会被 doc-builder 误解析为构造参数的同义词导致属性被渲染成参数交叉引用用方括号反引号语法如[~Robot.connect]不支持 Sphinx 角色:pymeth:等示例必须放在 fenced 代码块内并包含提示符触及硬件、GPU 或 Hub 下载的示例一律加# doctest: SKIP。6.4 文档质量的自动化关卡docstring 与文档的质量由多层检查保障全部可在 Makefile 中一键触发检查命令作用make check-docstrings运行 utils/check_docstrings.py 与check_config_docstrings.py校验Args:条目与签名一致、文档化默认值与真实默认值未漂移make doctest执行 utils/documentation_tests.txt 白名单文件中 docstring 示例确保示例仍然可运行make check-doctest-list校验documentation_tests.txt中条目未过期且按字母排序make fix-docstrings自动改写不匹配的Args:块并插入fill_docstring占位符再由人工补全从 utils/check_docstrings.py 的源码可以看到其MODULES_TO_CHECK列表当前含lerobot.robots是棘轮机制模块的 docstring 规范转换完成后才被纳入检查范围而OBJECTS_TO_IGNORE则暂时豁免尚未完成转换的对象。这种渐进式收紧策略让 CI 从第一天起就能保持绿色。提交 PR 前的标准自检命令组合是make check-docstrings make doctest pre-commit run --all-files跑完后用doc-builder build渲染一遍页面并亲眼检查最终效果The rendered page has been eyeballed 是 checklist 的最后一条。七、维护者速查清单依赖安装pip install -e . -r docs-requirements.txt外加 Node.js本地构建doc-builder build lerobot docs/source/ --build_dir 临时目录本地预览pip install watchdog后执行doc-builder preview lerobot docs/source/访问 http://localhost:3000新增文件创建.md/.mdx源文件 → 登记到 docs/source/_toctree.yml → 重启preview重命名/移动章节在原位置保留a id旧anchor映射目标用相对路径图片优先放 hf.co 托管数据集避免仓库内新增大体积二进制文件提交前make check-docstrings make doctest pre-commit run --all-files并本地构建目验渲染结果。遵循这套流程你就能与 LeRobot 仓库的文档 CI 保持完全同步任何 docstring 或.mdx变更都能安全、规范地落地到站点上。【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
