Transformers 文档工程实践doc-builder 构建、_toctree.yml 导航与 autodoc 语法详解【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本篇基于 Transformers 仓库的 docs/README.md“Writing docs” 官方指南系统讲解如何在本地用 doc-builder 构建与实时预览 Transformers 文档、如何向_toctree.yml侧边栏添加新页面、doc-builder 的专用 Markdown 语法callout、内部类链接、hfoptions选项卡、[[autodoc]]自动 API 参考、可测试代码块以及设备无关代码示例规范与auto_docstring文档字符串体系。读完后可独立完成一次从新建文档页、通过 CI 检查到本地预览的完整文档贡献流程。文档体系总览docs 目录结构与构建工具Transformers 的所有文档位于docs/source/lang/下按语言分目录组织en/、zh/、ja/、ko/等使用 Hugging Face 自研的 doc-builder 工具构建。仓库根目录下的 docs/README.md 是维护者编写文档的权威指南而 docs/TRANSLATING.md 则面向翻译贡献者。指南中有一个重要前提通常不需要在本地构建文档。只要 PR 触及docs/下的文件CI 机器人会自动构建预览并将链接以评论形式贴在 PR 上。本地构建的意义在于更快的迭代反馈drafting 阶段在提交 PR 之前先检查渲染效果。另外注意构建产物不要提交进仓库只有docs/source/下的变更会进入代码评审。本地构建与实时预览安装依赖在仓库根目录安装质量依赖和 doc-builder。对于只做文档工作[quality]extra 已经足够如果改动还涉及库代码、需要完整开发依赖集再安装[dev]pip install -e .[quality] pip install githttps://github.com/huggingface/doc-builder静态构建到临时目录将 Markdown 文件构建到一个临时目录中可用任意 Markdown 编辑器查看渲染结果doc-builder build transformers docs/source/en/ --build_dir ~/tmp/test-build其中transformers是包名docs/source/en/是英文文档的源目录中文等其他语言只需替换为对应的语言目录。浏览器实时预览安装 watchdog 后运行preview即可在http://localhost:5173获得带热更新的浏览器预览pip install watchdog doc-builder preview transformers docs/source/en/[!WARNING]preview只会拾取启动时已存在的文件。新增全新页面后需要先更新_toctree.yml再重启preview才能看到新页面。向文档添加新页面_toctree.yml 导航机制页面以 Markdown.md文件形式存放在docs/source/lang/下但只有在 docs/source/en/_toctree.yml 中登记之后才会出现在侧边栏。新页面必须两步走在docs/source/en/或对应语言目录下创建 Markdown 文件。命名与 license 头部应与现有页面保持一致——最快的起步方式是复制一个相似页面作为模板在docs/source/en/_toctree.yml中添加一条指向该文件的记录文件名不带.md扩展名。每个条目有两个字段local相对于docs/source/lang/的文件路径不带扩展名title显示在侧边栏的人类可读标签。对于嵌套在子章节内的页面需要把条目加进内层sections列表。这正是_toctree.yml的实际结构每个节点可带isExpanded侧边栏是否默认展开和sections子列表。以真实的 Contribute 小节为例见 docs/source/en/_toctree.yml 中title: Contribute节点- isExpanded: false sections: - local: contributing title: Contribute to Transformers - local: my_new_contributor_guide title: My new contributor guide title: Contribute_toctree.yml全文件约 1600 行按“Get started / Base classes / Training / Tasks”等顶层分组逐级展开侧边栏的层级完全由这份 YAML 树决定。仓库的 CI 一致性检查列表中包含doc_toc检查器见 Makefile 中的REPO_CONSISTENCY_CHECKERS它会校验_toctree.yml与docs/source/下实际文件的一致性所以“建了文件却忘了登记”这类疏漏会在 CI 中被捕获。设备无关的代码示例规范Device Agnostic Snippets由于读者会在 NVIDIA GPU、AMD ROCm、Intel XPU、Apple MPS、Ascend NPU 以及 CPU 上运行文档中的代码片段指南明确要求避免硬编码cuda。核心规则仅在确实需要自动分发automatic dispatch时使用device_mapautoCUDA 专属示例保留显式cuda用inputs.to(model.device)迁移输入而不是.to(cuda)或.cuda()同步使用torch.accelerator.synchronize()计时用torch.Event(enable_timingTrue)显存辅助函数位于torch.accelerator.memory下如torch.accelerator.memory.empty_cache()与torch.accelerator.memory.max_memory_allocated()如果确实需要设备字符串使用device torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else cpu只在真正与 CUDA 绑定的场景保留cuda工具链说明nvcc、nvidia-smi、NVIDIA 专属后端、PyTorch API 名称如use_cuda_graph以及从真实运行中复制的示例输出。这一规范与仓库的硬件抽象演进一致从源码结构看torch.accelerator是 PyTorch 2.10 引入的跨加速器统一入口Transformers 的文档示例全面转向它是为了让同一段代码在多厂商硬件上都能直接复制运行。doc-builder 扩展语法详解doc-builder 接受标准 Markdown外加若干专属扩展。以下逐一说明在 Transformers 文档中实际可见的写法。Tip 与 Warning callout使用 GitHub 风格的引用块标注提示与警告 [!TIP] Use device_mapauto to let Transformers place model shards across available devices. [!WARNING] from_pretrained downloads the full checkpoint on first use. Set cache_dir to control where it lands.旧页面可能仍在使用遗留的Tip组件新内容应统一使用 blockquote 形式。类与函数的内部链接将类、函数或方法名用“方括号 反引号”包裹即可生成指向其 API 文档页的链接由 doc-builder 自动解析Use [AutoModel] to load a model from a checkpoint, then call [~PreTrainedModel.from_pretrained].几个变体名称前加~前缀只渲染最后一段from_pretrained而非完整的PreTrainedModel.from_pretrained嵌套在子模块中的对象需在反引号内写全路径如utils.ModelOutput同一语法也可以链接到其他 Hugging Face 库的对象例如accelerate.Accelerator。选项卡Tabbed options用hfoptions组件把可选方案CLI vs Python、不同后端等渲染为选项卡。这是整个文档库高频使用的写法在docs/source/en/下搜索hfoptions可看到数十个页面在用如 docs/source/en/installation.md、docs/source/en/quicktour.md等。标准写法hfoptions idinstall hfoption idpip bash pip install transformers /hfoption hfoption iduv bash uv pip install transformers /hfoption /hfoptions外层id是选项卡组的锚点标识内层每个hfoption的id决定选项卡标签。[[autodoc]]自动 API 参考[[autodoc]]用于直接渲染类或函数的 docstring标记会拉取描述、参数以及对类而言全部公开方法## AutoModel [[autodoc]] AutoModel[!IMPORTANT][[autodoc]]之后必须留一个空行否则 CI 检查会失败。三种细化方式限定方法用项目符号子列表只渲染指定方法[[autodoc]] BertTokenizer - build_inputs_with_special_tokens - get_special_tokens_mask拉入默认不文档化的方法如__call__列表首行写all再补充额外项[[autodoc]] BertTokenizer - all - __call__在docs/source/en/下的 internal API 页面中[[autodoc]]是绝对主力语法——例如docs/source/en/internal/generation_utils.md单文件就使用了 60 多处整个 API 参考几乎完全由它自动生成。可测试代码块Testable code blocks给 Python 代码栅栏打上runnable标签可附加:label即标记为“可测试示例”doc-builder 会在渲染输出中剥掉该标注而 CI 会真正执行这些片段以验证文档与库行为不脱节py runnable:quickstart from transformers import pipeline pipe pipeline(sentiment-analysis) print(pipe(I love this!)) 这种机制解释了仓库中docs/source/en/quicktour.md、docs/source/en/models.md等页面代码块为何带runnable标注——它们不是普通示例而是有 CI 背书的可执行文档测试。Docstring 编写规范auto_docstring 与手写文档字符串docs/README.md 指出库中大多数 docstring 是在源码里自动生成的尤其是modeling_*.py、configuration_*.py、processing 与 tokenizer 文件。对于模型类与forward方法应使用auto_docstring装饰器该文档页在 _toctree.yml 的 Contribute 小节中登记为local: auto_docstring标题 “Auto-generating docstrings”。它让共享参数与返回值在所有模型文件中保持一份一致的文档而不必在每个模型文件里重复完整的Args:块。仅在以下情况使用手写 docstring遵循 Google Python Style Guide对象不在auto_docstring覆盖范围内方法需要描述模型特有的行为。格式检查make style运行make style用 Ruff 格式化 docstring 与代码示例。对照仓库根目录的 Makefile 可以看到其实现STYLE_CHECKERS : ruff_check, ruff_format, init_isort, sort_auto_mappings style: python utils/checkers.py $(STYLE_CHECKERS) --fix即make style等价于通过 utils/checkers.py 顺序执行ruff_check、ruff_format、init_isort、sort_auto_mappings四个检查器并带--fix自动修复。两个实操注意点该脚本可能因语法错误而失败建议先git commit再运行以便出问题时回滚若改动同时触及src/下的库代码CI 还会并行跑make check-code-quality与make check-repository-consistency两套检查文档贡献者至少应保证check-repository-consistency中与文档相关的检查doc_toc、docstrings、doctest_list等通过。图片与二进制资源一律托管到 Hub最后一项强约束不要把图片、视频或其他二进制资源提交进仓库因为它们会显著膨胀仓库体积。文档图片的标准托管位置是 Hub 上的huggingface/documentation-images数据集文档中直接以 URL 引用。对于外部贡献者的 PR正确流程是把图片附在 PR 里请 Hugging Face 维护者将其迁移到该数据集。这条规则与“构建产物不要提交、只有docs/source/变更被评审”共同构成了文档目录的卫生准则纯文本Markdown YAML进仓库媒体资源走 Hub。小结一次文档贡献的完整清单结合 docs/README.md 与仓库实际结构一次完整的文档贡献应满足在docs/source/lang/下新建.md页面复制相似页面以保持命名与 license 头部一致在docs/source/lang/_toctree.yml对应层级的sections中登记local/title条目代码片段遵守设备无关规范model.device、torch.accelerator.*CUDA 字样仅限真正 CUDA 专属场景提示用[!TIP]/[!WARNING]blockquote可执行示例打py runnable标签API 页用[[autodoc]]后留空行图片放 Hub 数据集而非仓库先 commit 再make style不提交构建产物其余交给 PR 上的文档预览机器人验证渲染效果。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考