Datasets 文档构建实战用 doc-builder 搭建、预览与维护官方文档站【免费下载链接】datasets The largest hub of ready-to-use datasets for AI models with fast, easy-to-use and efficient data manipulation tools项目地址: https://gitcode.com/gh_mirrors/da/datasets本文是一份围绕 Hugging Facedatasets仓库文档工程docs/README.md的完整实操指南讲解如何在本地用doc-builder工具链构建、预览和维护 Datasets的官方文档站点。读完本文你将掌握从环境准备、MDX 构建、本地热更新预览到_toctree.yml导航组织、节标题迁移、Google 风格 docstring 写作规范的一整套文档工作流能够像维护一个正式开源项目文档那样安全地修改、验证并提交文档改动。文档工程的总体工作流 Datasets的官方文档并不手工维护成一份巨型 Markdown而是由docs/source/目录下的多篇.md/.mdx源文件组成再借助 Hugging Face 的doc-builder工具构建渲染成站点。整个工作流包含四个环节准备构建环境安装文档依赖与doc-builder工具构建文档将docs/source/下的源文件编译为 MDX 产物本地预览起一个本地服务实时检查渲染效果按规范扩展新增页面、调整导航、迁移节标题并遵守统一的写作规范。一个关键原则是构建文档只是为了本地检查效果比如提交前确认页面长什么样构建产物不需要git commit到仓库中。第一步准备文档构建环境安装文档依赖在仓库根目录执行以下命令安装构建文档所需的全部依赖包pip install -e .[docs]其中-e表示以可编辑editable模式安装当前仓库源码[docs]是setup.py中定义的 extras。查看 setup.py 可以看到DOCS_REQUIRE的具体内容DOCS_REQUIRE [ # Following dependencies are required for the Python reference to be built properly transformers, torch, tensorflow2.6.0, ]也就是说docsextra 会额外安装transformers、torch、tensorflow2.6.0它们的作用是让 Python API 参考即docs/source/package_reference/下的类与方法文档在构建时能够正确解析类型签名与 docstring。该 extra 在 setup.py 中注册为docs: DOCS_REQUIRE并且也被devextra 复用setup.py。安装 doc-builder 工具接着安装 Hugging Face 专门的文档构建工具doc-builderpip install githttps://github.com/huggingface/doc-builder该工具负责把docs/source/下的 Markdown / MDX 源文件编译成最终渲染用的文档产物并承担本地预览服务。第二步构建文档环境就绪后在仓库根目录运行doc-builder build datasets docs/source/ --build_dir ~/tmp/test-build各参数含义如下参数含义datasets包名doc-builder据此关联当前仓库的 Python 包结构docs/source/文档源文件目录--build_dir ~/tmp/test-build构建输出目录可替换为任意你偏好的临时目录该命令会自动创建--build_dir指定的目录并生成将渲染到主站点的 MDX 文件。构建完成后可以用任意 Markdown 编辑器打开这些产物检查效果。由于输出的是独立目录构建过程不会污染仓库本身也无需提交这些生成文件。第三步本地预览文档构建之外doc-builder还提供实时预览功能方便在写文档时边改边看。安装 watchdog预览依赖文件系统监听模块watchdogpip install watchdog启动预览服务doc-builder preview datasets docs/source/启动后文档可通过 http://localhost:3000 在浏览器中查看。如果你已经开了 PR预览 bot 也会在 PR 评论区贴出一个包含你改动的文档链接无需本地构建即可评审效果。这里有一个容易踩坑的细节preview命令只对已存在的文档文件生效。当你新增了一个全新的文件时必须先更新_toctree.yml让站点知道该页面然后按ctrl-c停止预览服务并重新执行doc-builder preview ...新增页面才会出现。组织文档导航_toctree.yml 与重定向新增一个页面文档导航完全由docs/source/_toctree.yml控制。新增页面的流程分两步在docs/source/下新建一个.md或.mdx文件两种扩展名均被接受在 docs/source/_toctree.yml 中把不带扩展名的文件名挂到正确的 toc-tree 节点下。以当前仓库的_toctree.yml为例站点被划分为Get started、Tutorials、How-to guides、Conceptual guides、Reference等大节例如- sections: - local: index title: Datasets - local: quickstart title: Quickstart - local: installation title: Installation title: Get started其中local字段就是docs/source/下的文件名不含扩展名title是侧边栏显示的标题。新增文件时把页面挂到语义最贴切的章节下即可如果不确定放哪一节可以在 GitHub Issue 或 PR 中询问维护者。此外仓库还维护了一个旧页面的重定向映射 docs/source/_redirects.yml例如quicktour: quickstart、dataset_streaming: stream、package_reference/logging_methods: package_reference/utilities。当你重命名页面时也可以借助这类映射保持旧链接可用。构建配置docs/source/_config.py 存放了文档构建的少量全局配置例如INSTALL_CONTENT定义了文档内嵌 notebook 首单元格的安装代码! pip install datasets transformers以及default_branch_name main、version_prefix 等参数。需要为文档页添加一键安装提示或调整版本前缀时改的就是这个文件。重命名节标题与移动节保留旧锚点文档迭代中经常要重命名节标题或把某个节从一篇文档移动到另一篇。由于这些节标题的锚点anchor可能已被 Issue、论坛帖子和社交媒体引用直接改名会让数月后的读者点开死链。因此约定在原位置文件末尾保留一张被移动的节映射表关键是保留原始锚点。如果只是把 Section A 重命名为 Section B可以在文件末尾添加Sections that were moved: [ a href#section-bSection A/aa idsection-a/a ]如果节被移到了另一个文件则指向新文件Sections that were moved: [ a href../new-file#section-bSection A/aa idsection-a/a ]链接新文件时建议使用相对路径风格这样版本化文档versioned docs也能继续正常工作。写作规范Google 风格 docstring 与 Markdown 扩展huggingface/datasets的文档遵循 Google 风格的 docstring与 sphinxcontrib-napoleon 一致但可以直接用 Markdown 编写。新增教程的两步流程在docs/source/下新建.rst或.md文件在docs/source/_toctree.yml的对应 toc-tree 中链接该文件。仓库中docs/source/tutorial.md、docs/source/how_to.md与docs/source/quickstart.mdx、docs/source/load_hub.mdx等页面就是通过这种方式组织在Tutorials和How-to guides章节下的。代码与对象引用需要放入code的值一律用反引号包裹例如True、None以及参数名、字符串字面量。当提及类、函数或方法时推荐使用内部链接语法让构建工具自动为其加上文档链接[XXXClass]或[function]要求该类/函数在主包中[table.InMemoryTable]带路径的引用链接文字显示完整路径[~table.InMemoryTable]加~后链接文字只显示类名InMemoryTable[XXXClass.method]或[~XXXClass.method]同样适用于方法。Args 参数块规范参数块用Args:也接受Arguments:或Parameters:开头换行后缩进书写。参数后依次是类型张量还需给出 shape、冒号和描述Args: n_layers (int): The number of layers of the model.描述过长需要换行时继续增加一级缩进。可选参数或带默认值的参数遵循固定格式——注意省略 defaults toNone默认就是None时不写且参数类型与默认值所在的第一行不能折行但缩进的描述部分可以写任意多行Args: x (str, *optional*): This argument controls ... a (float, *optional*, defaults to 1): This argument is used to ...以datasets库的实际 docstring 为例Dataset.map的文档就大量使用这种格式来描述num_proc、batched、cache_file_name等参数。Returns 返回块规范返回块用Returns:开头首行写返回类型之后不再额外缩进元素。单值返回示例Returns: List[int]: A list of integers in the range [0, 1] --- 1 for a special token, 0 for a sequence token.多对象元组返回示例首行给出tuple(...)类型随后用- **名称**列表说明每个元素及其可选条件、类型、shape 与含义Returns: tuple(torch.FloatTensor) comprising various elements depending on the configuration ([BertConfig]) and inputs: - ** loss** (*optional*, returned when masked_lm_labels is provided) torch.FloatTensor of shape (1,) -- Total loss as the sum of the masked language modeling loss and the next sequence prediction (classification) loss. - **prediction_scores** (torch.FloatTensor of shape (batch_size, sequence_length, config.vocab_size)) -- Prediction scores of the language modeling head (scores for each vocabulary token before SoftMax).多行代码块多行代码示例用 Markdown 的三重反引号包裹放在示例段落中即可 # first line of code # second line # etc 图片的使用约定由于仓库增长迅速应避免向仓库提交会显著增大体积的文件图片、视频等非文本文件。图片建议托管到 hf.co 上的数据集例如huggingface/documentation-images在文档中通过 URL 引用。外部贡献者也可以先把图片放进自己的 PR再请 Hugging Face 成员协助迁移到该数据集。这一约定保证了文档仓库保持轻量。示例 docstring让读者开箱即用文档中每个类或函数的示例都应给出最小、清晰的实践用法并包含合理的预期输出——读者往往会先跑示例再读定义所以示例必须真实可用。Example:块的语法如下Example: py from datasets import load_dataset ds load_dataset(cornell-movie-review-data/rotten_tomatoes, splitvalidation) def add_prefix(example): ... example[text] Review: example[text] ... return example ds ds.map(add_prefix) ds[0:3][text] [Review: compassionately explores the seemingly irreconcilable situation between conservative christian parents and their estranged gay and lesbian children ., Review: the soundtrack alone is worth the price of admission ., Review: rodriguez does a splendid job of racial profiling hollywood style--casting excellent latin actors of all ages--a trend long overdue .] # process a batch of examples ds ds.map(lambda example: tokenizer(example[text]), batchedTrue) # set number of processors ds ds.map(add_prefix, num_proc4) 这个示例同时覆盖了三个常见用法单样本map、batchedTrue的批量处理、num_proc4的多进程并行——这些能力对应仓库中 arrow_dataset.py 的Dataset.map实现以及 parallel.py 中num_proc对应的并行调度逻辑读者可以直接在本地复现。文档质量保障除了doc-builder的构建与预览仓库还提供了代码质量工具链来约束文档配套的代码风格。查看仓库根目录的 Makefilequality: ruff check $(check_dirs) setup.py # linter ruff format --check $(check_dirs) setup.py # formatter style: ruff check --fix $(check_dirs) setup.py # linter ruff format $(check_dirs) setup.py # formatter test: python -m pytest -n auto --distloadfile -s -v ./tests/其中check_dirs : tests src benchmarks utils。代码风格采用 Ruff配置见 pyproject.toml行宽 119文档相关的示例代码和 docstring 应与之保持一致。提交前运行make quality做静态检查、make style自动格式化文档改动涉及的测试则通过make test验证。小结 Datasets的文档体系是一个完整的工程化流程用pip install -e .[docs]与doc-builder搭建环境用doc-builder build生成 MDX 产物用doc-builder preview实现本地实时预览通过docs/source/_toctree.yml组织导航、docs/source/_redirects.yml维护重定向并以 Google 风格的 docstring 规范保证 API 文档的一致性与可引用性。掌握这套工作流后无论是为datasets新增使用教程、扩充 API 参考还是重构现有章节你都能在本地完整验证渲染效果后再安全地提交改动。【免费下载链接】datasets The largest hub of ready-to-use datasets for AI models with fast, easy-to-use and efficient data manipulation tools项目地址: https://gitcode.com/gh_mirrors/da/datasets创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考