Ray 文档示例 Notebook 编写指南：基于 MyST 模板 template.md 的完整实战

Ray 文档示例 Notebook 编写指南：基于 MyST 模板 template.md 的完整实战

【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray

本指南以 Ray 仓库中的文档模板 template.md 为骨架，系统讲解如何用 Markdown 编写可执行的 Jupyter Notebook 式文档（MyST 格式），覆盖 YAML 前端元数据、code-cell代码单元、六种单元格标签、提示框、数学公式与发布工作流。读完本文，你将能够直接复用该模板为 Ray 的 Tune、Serve、Ray Data 等模块撰写可运行、可被 CI 自动测试的示例文档，并掌握本地构建与验证的完整方法。

模板在 Ray 文档体系中的定位

Ray 的文档（源码位于 doc/source）构建在 Sphinx 之上，同时支持 reStructuredText（rST）与 MyST Markdown 两种标记语言，并完整支持 Jupyter Notebook 等可执行格式。仓库维护了两个等价模板：

• template.md：以 Markdown 文本表示的 Notebook（MyST 格式），是推荐的起点；
• template.ipynb：与之内容一一对应的标准.ipynbNotebook 文件。

根据 docs.md 的说明，新增页面必须使用 MyST Markdown（.md），lint 检查会拒绝新提交的.rst文件（对既有.rst的编辑不受影响）。撰写可执行示例时，社区推荐“先写.md，最后再用 jupytext 转换成.ipynb”，因为纯文本形式的 MyST 更容易添加标签、做代码审查与差异对比。

依赖侧，requirements-doc.txt 显式声明了myst-parser==5.1.0（Markdown 解析）、myst-nb==1.4.0（Notebook 渲染与执行）和jupytext==1.15.2（格式互转），并在 conf.py 中启用myst_nb扩展——这就是模板中各类 MyST 语法得以生效的底层机制。

文件头：jupytext 前端元数据与内核规格

模板以 YAML 前端元数据（front matter）开头，这是让一个.md文件被 jupytext 识别为 MyST Notebook 的“身份证”：

--- jupytext: text_representation: extension: .md format_name: myst kernelspec: display_name: Python 3 language: python name: python3 ---

各字段的作用如下：

kernelspec是 Notebook 的必需要素——正如 docs.md 所述，Notebook 需要定义内核规格，告诉 notebook server 如何解释并运行其中的代码。如果将来要写 R 或 Julia 内核的示例，改这一节即可。

可引用标签、脚注、边注与内嵌 rST

模板演示了四种非代码层的 Markdown 扩展能力。

引用标签（reference section label）：在任意标题前加一行(标签名)=，即可为文档章节建立可交叉引用的锚点：

(document-tag-to-refer-to)= # Creating an Example

该标签可在 rST 文档中用{ref}引用，例如See {ref}the thing that I labeled ``，也可以从其他.md页面链接过来。这对组织大型文档目录（如 Tune 的 user guide 与 example 之间互链）非常有用。

脚注（footnote）：使用 Markdown 标准脚注语法：

You can also easily define footnotes.[^example] [^example]: This is a footnote.

边注（margin）：{margin}指令用于放置不进入正文主流程的补充说明，适合提示、延伸阅读等次要信息：

```{margin} You can create margins with this syntax for smaller notes that don't make it into the main text.

**内嵌 rST 指令（eval-rst）**：MyST 兼容 CommonMark，可以直接写普通 Markdown；但当你需要执行 rST 指令（例如 `.. note::`、`.. warning::`）时，用 `{eval-rst}` 包裹即可： ```text ```{eval-rst} .. note:: A note written in reStructuredText.

这在需要复用存量 rST 生态指令、又不想放弃 Markdown 书写体验的场景下非常实用。此外 [conf.py](https://link.gitcode.com/i/9566de076850da55d501281dbc38ed82) 中 `default_role = "code"` 使单个反引号也按代码处理，开发者在 Markdown 中写 `` `code` `` 不会被误渲染为斜体或链接。 ## 添加可执行代码单元：code-cell 指令 在 MyST Notebook 中，代码单元使用 `code-cell` 指令。模板中的完整示例同时用到了 Ray 的三大子模块——分布式运行时（`ray`）、强化学习库 RLlib（`ray.rllib`）与在线服务（`ray.serve`）： ```text ```{code-cell} python3 import ray import ray.rllib.agents.ppo as ppo from ray import serve def train_ppo_model(): trainer = ppo.PPOTrainer( config={"framework": "torch", "num_workers": 0}, env="CartPole-v0", ) # Train for one iteration trainer.train() trainer.save("/tmp/rllib_checkpoint") return "/tmp/rllib_checkpoint/checkpoint_000001/checkpoint-1" checkpoint_path = train_ppo_model()

该示例在浏览器中会以“可运行代码 + 输出”的形式渲染，读者可以一键执行。需要特别提醒的是：**模板示例使用的是 RLlib 旧版 API**（`ray.rllib.agents.ppo` 与 `PPOTrainer`）。从当前仓库源码看，该命名空间已被取代——[ppo.py](https://link.gitcode.com/i/01f17ef37545be017f49b448691a1387) 中定义并导出的入口是 `ray.rllib.algorithms.ppo.PPOConfig`，其 docstring 给出了现代写法： ```python from ray.rllib.algorithms.ppo import PPOConfig config = PPOConfig() config.environment("CartPole-v1") config.env_runners(num_env_runners=1) config.training(gamma=0.9, lr=0.01, kl_coeff=0.3, train_batch_size_per_learner=256) algo = config.build() algo.train()

因此实际撰写文档时应优先使用ray.rllib.algorithms.*新 API，模板中的旧写法仅作语法演示。

关于执行行为：myst_nb是否真正执行代码单元由 conf.py 中的nb_execution_mode控制，默认取环境变量RUN_NOTEBOOKS，未设置时为"off"（即文档构建默认不执行 notebook，仅渲染源码与已缓存输出）；本地需要强制重跑全部单元时，可设RUN_NOTEBOOKS=force。

隐藏与移除单元格：六种标签详解

模板的核心实用功能之一，是通过:tags:控制单元格在文档页面中的可见性。六种标签分为“隐藏”与“移除”两类，区别在于是否保留单元本身：

所有标签在.ipynb文件中同样有效（对应单元格metadata.tags），例如模板的 Jupyter 版本 template.ipynb 中，hide-cell与remove-cell就以"tags": ["hide-cell"]的元数据形式存在。

模板中的两个实例：

```{code-cell} python3 :tags: [hide-cell] # This can be useful if you don't want to clutter the page with details. import ray import ray.rllib.agents.ppo as ppo from ray import serve

```text ```{code-cell} python3 :tags: [remove-cell] ray.shutdown()

这两者的用途差异很典型：`hide-cell` 用于“读者可能需要但不想默认看到”的辅助代码（如批量导入）；`remove-cell` 用于“运行需要但展示无意义”的收尾代码（如 `ray.shutdown()`）。 **实战价值最高的场景是计算密集型 Notebook**。正如 [docs.md](https://link.gitcode.com/i/b027081fe65659198cd583a4c43fe340) 所建议的：先给读者看真实规模的参数，再用 `remove-cell` 塞入一份“跑得快”的替身参数，让 CI 测试不至于超时： ```text ```{code-cell} python3 num_workers = 8 num_gpus = 2

```text ```{code-cell} python3 :tags: [remove-cell] num_workers = 0 num_gpus = 0

仓库中的真实示例也大量使用这些标签，例如 [highly_parallel.ipynb](https://link.gitcode.com/i/79760ab9b627a7987fc5c060a8267811) 中对 `ray.init(address='auto')` 使用了 `remove-output`，避免把集群地址等运行时输出写进文档。这套机制让“文档可读性”与“CI 可测性”得以兼顾。 ## 提示框与边栏（admonitions） 模板演示了 MyST 的提示框语法，用 `:::` 包裹指令名即可： ```text :::{tip} Here's a quick tip. ::: :::{note} And this is a note. :::

tip、note、warning、important等均可用。底层由 conf.py 的myst_enable_extensions中的html_admonition扩展提供支持，同时启用的还有colon_fence（即:::冒号围栏语法本身）。这些提示框适合在示例中标注版本注意点、性能提醒等，是模板中“快速提示”与“说明”两类文案的标准承载方式。

数学公式与 MyST 扩展

模板末尾展示了 LaTeX 公式支持：

\begin{equation} \frac {\partial u}{\partial x} + \frac{\partial v}{\partial y} = - \, \frac{\partial w}{\partial z} \end{equation} \begin{align*} 2x - 5y &= 8 \\ 3x + 9y &= -12 \end{align*}

equation与align*环境的渲染由 MyST 解析器配合 conf.py 中启用的dollarmath、amsmath扩展完成（后者支持行间对齐等 AMS 数学环境）。如果你在 Tune 或 RLlib 示例中需要展示目标函数、损失公式或复杂度推导，直接使用该语法即可，无需引入额外插件。

从模板到正式示例的发布工作流

拿到模板后，完整的落地路径分为写作、转换、构建验证三步。

第一步：写作。复制 template.md 作为起点，在doc/source/<子项目>/examples/等目录下新建文件（如 Tune 示例放在doc/source/tune/examples，其他子项目结构类似）。保留文件头的 jupytext 元数据与kernelspec，按上文语法组织 Markdown 正文、code-cell与各类标签。

第二步：转换。写作完成后用 jupytext 生成标准 Notebook：

jupytext your-example.md --to ipynb

反向转换同样简单：jupytext your-example.ipynb --to myst转回 MyST Markdown；jupytext your-example.ipynb --to py则导出纯 Python 脚本，可用于快速检查整段代码能否无错运行。

第三步：构建验证。在ray/doc目录下按需选择构建方式（详见 docs.md 与 Makefile）：

# 全量构建（推荐用于新增/删除/重命名文件的场景） make clean make develop # 增量构建 + 浏览器实时预览（适合频繁小幅修改） make local # 复现 Read the Docs 的完整构建（fail_on_warning 生效，任何 Sphinx 警告都会失败） make rtd-build

• make local会从 CI 缓存中拉取最近一次上游构建产物，只重编你改动影响的页面，构建完成自动打开浏览器，文件变更后自动重载，Ctrl+C停止；
• make rtd-build前会先执行rtd_doctor.py环境预检（make rtd-doctor可单独运行），校验 Python 版本与requirements-doc.lock.txt锁定依赖是否与 Read the Docs 一致，存在漂移会直接报错（可用RTD_DOCTOR_ARGS=--warn-only降级为警告）；
• 若本地构建环境无法匹配 Read the Docs，构建依赖请使用锁文件pip install -r requirements-doc.lock.txt，不要加-U。

关于 CI 测试：放置在 examples 目录中的 Notebook 会被 CI 系统自动执行测试；需要控制测试规模时，就用上文remove-cell标签替换参数。新增页面还必须在父文档的 toctree 中显式登记（参见 docs.md），并视子项目要求补充到对应的 overview 索引页中。

相关文件索引

按此流程，你既可以用 MyST 模板写出语法规范的示例文档，又能借助标签机制让 notebook 同时满足“读者体验”与“CI 可测”两个要求，并在本地完成与线上一致的构建验证。

【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址: https://gitcode.com/gh_mirrors/ra/ray