Gymnasium 贡献指南：从类型检查、Git Hooks 到文档构建的完整开发流程-迪斯科星球

Gymnasium 贡献指南：从类型检查、Git Hooks 到文档构建的完整开发流程

【免费下载链接】GymnasiumA standard API for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)项目地址: https://gitcode.com/GitHub_Trending/gy/Gymnasium

本篇技术指南以 Gymnasium 官方贡献规范（CONTRIBUTING.md）为骨架，系统讲解向这个强化学习环境标准库提交贡献时的完整工程流程：如何用ty做类型检查、如何借助pre-commit在本地复现 CI 检查、如何遵循 Google 风格的 Docstring 规范，以及如何在本仓库内构建 Sphinx 文档站。读完本文，你将掌握在 Gymnasium 仓库中安全提交代码、通过全部质量门禁并构建本地文档的完整实战方案。

一、Gymnasium 接受哪些形式的贡献

Gymnasium 是 Farama Foundation 维护的强化学习环境标准 API（前身为 OpenAI Gym），其核心价值在于环境行为的稳定与可复现。因此 CONTRIBUTING.md 对贡献形式做了明确界定：

当前接受的贡献形式：

Bug 报告（Bug reports）：需要特别注意的是，修改环境行为应被最小化——因为任何行为变更都要求发布新版本环境，并会破坏不同版本之间实验结果的横向可比性；
Bug 修复的 Pull Request（Pull requests for bug fixes）；
文档改进（Documentation improvements）；
新功能（Features）。

明确不接受的贡献形式：

新环境（New environments）：这是最容易被误解的一点。Gymnasium 核心仓库不接收新增环境，环境通常通过第三方扩展或独立仓库提交。

这一边界与仓库的实际结构相互印证：gymnasium/envs/下的环境按 box2d、classic_control、mujoco、toy_text 等模块组织，而docs/environments/third_party_environments.md则专门用于承载第三方环境的说明，说明官方有意将核心环境与第三方扩展隔离管理。

二、类型检查：使用`ty`并理解其配置

项目使用 Astral 出品的ty作为类型检查器。要在本地执行类型检查，首先按官方安装说明安装ty，然后运行：

ty check .

或通过 pre-commit 流程执行（下文详述）：

pre-commit run --all-files

`ty`的配置存放位置

ty的配置位于仓库根目录 pyproject.toml 的[tool.ty.*]段，内容包括当前支持类型检查的包含/排除文件列表。核心配置如下：

[tool.ty.src] include = ["gymnasium"] exclude = ["tests", "**/node_modules", "**/__pycache__"] [tool.ty.analysis] replace-imports-with-any = ["Box2D.**", "mujoco.**", "glfw.**"] respect-type-ignore-comments = false [tool.ty.terminal] error-on-warning = false [tool.ty.environment] python-version = "3.10" python-platform = "all" extra-paths = [] [tool.ty.rules] invalid-argument-type = "warn" # TODO remove invalid-assignment = "warn" # TODO remove invalid-method-override = "warn" # TODO remove invalid-return-type = "warn" # TODO remove missing-argument = "warn" # TODO remove unresolved-attribute = "warn" # TODO remove unresolved-import = "warn" # TODO remove unsupported-operator = "warn" # TODO remove

对上述配置的源码级解读：

include只覆盖gymnasium包本体，tests目录被显式排除；
replace-imports-with-any将 Box2D、mujoco、glfw 等可选/重量级第三方依赖的导入替换为Any，避免在未安装这些库的环境下因导入失败而阻塞类型检查，这也与 pyproject.toml 中[project.optional-dependencies]将box2d、mujoco列为可选依赖的定位一致；
[tool.ty.rules]中所有规则当前均设为warn级别（并留有TODO remove注释），说明项目正处于逐步收紧类型检查的过渡阶段，允许警告存在但阻止硬性错误。

为更多模块补充类型标注

如果你想为某个尚未覆盖的模块添加类型标注，ty的包含/排除文件列表就在pyproject.toml的[tool.ty.src]段维护。修改该配置后重新运行ty check .即可验证新增模块是否通过检查。

三、Git Hooks：在本地复现 CI 的完整检查链

CI 会在推送到 Gymnasium 仓库的新代码上运行多项检查。为免去等待 CI 的往返，CONTRIBUTING.md 给出两步本地复现方案：

安装pre-commit；
运行pre-commit install安装 Git Hooks。

完成上述两步后，每次git commit都会自动触发这些 Hooks。相关操作命令：

# 手动运行全部检查 pre-commit run --all-files # 跳过检查（不推荐） git commit --no-verify

注意：首次提交时可能需要手动运行pre-commit run --all-files数次才能通过——因为每个格式化工具会先格式化代码并在第一次运行时失败，第二次运行才会通过。这是 pre-commit 工具链的典型行为，属于正常现象。

Hooks 链路的真实构成

仓库根目录的 .pre-commit-config.yaml 揭示了实际运行的检查链，共分四组：

基础文件检查（pre-commit-hooks v6.0.0）：符号链接检查（check-symlinks、destroyed-symlinks）、尾随空白（trailing-whitespace）、文件末尾换行（end-of-file-fixer）、YAML/TOML/AST 语法校验（check-yaml、check-toml、check-ast）、大文件与合并冲突检测（check-added-large-files、check-merge-conflict）、shebang 校验、私钥泄露检测（detect-private-key）以及调试语句检测（debug-statements）；
拼写检查（codespell v2.4.1）：通过--ignore-words-list排除reacher、referenc、wile等强化学习领域词与专有名词的误报；
代码风格（ruff-pre-commit v0.14.10）：先运行ruff-check --fix做 lint 并自动修复，再运行ruff-format做格式化；
类型检查（ty-pre-commit v0.0.54）：运行tyhook。

在 pyproject.toml 中，ruff 的 lint 规则选择为E（pycodestyle 错误）、F（pyflakes）、UP（pyupgrade）、I（isort）、D（pydocstyle）、B（bugbear），并忽略E501（行长度）。同时，.pre-commit-config.yaml 中以注释形式保留了 flake8 与 pydocstyle 的旧配置，说明项目经历过从 flake8/pydocstyle 到 ruff 的工具链迁移，D规则由 ruff 内置的 pydocstyle 支持接管。

Pull Request 的完整测试

除了 pre-commit，PR 还会针对整个项目运行基于pytest的测试套件。本地可在仓库根目录直接运行：

pytest

如果修改了任何 doctest，则需额外运行：

pytest --doctest-modules --doctest-continue-on-failure gymnasium

--doctest-continue-on-failure保证即使某个 doctest 失败，也会继续执行其余 doctest，从而一次拿到全部失败信息。在 pyproject.toml 的[tool.pytest.ini_options]中，项目配置了filterwarnings = ["ignore::DeprecationWarning:gymnasium.*:"]来屏蔽 Gymnasium 包自身的弃用警告噪音。仓库tests/目录下覆盖了spaces、envs、vector、wrappers、utils等各子系统的测试，例如 tests/test_core.py 验证核心Env接口、tests/vector/ 验证向量环境、tests/wrappers/ 验证各包装器行为。

四、Docstring 规范：Google 风格 + pydocstyle 校验

pydocstyle 已被纳入 pre-commit 流程，所有新函数必须遵循 Google docstring 风格。具体要求如下：

函数：必须提供简短 docstring（单行说明函数用途），或多行 docstring 逐个记录参数与返回值（如果有）；
文件与类：新文件和类需要顶部 docstring，概述该文件/类的用途；
类：代码块示例应放在类顶部 docstring 中，而不是构造函数参数中。

本地校验命令：

pre-commit run --all-files # 或 pydocstyle --source --explain --convention=google

当 docstring 校验失败时，--source与--explain会给出失败的源码位置与原因说明。

在仓库配置层面，pyproject.toml 中[tool.ruff.lint.pydocstyle]设置了convention = "google"，将 Google 约定固化进 ruff 的D规则；同时通过[tool.ruff.lint.per-file-ignores]暂时豁免了gymnasium/envs/box2d/*、gymnasium/envs/classic_control/*、gymnasium/envs/mujoco/*、gymnasium/envs/toy_text/*及tests/*、docs/*的 docstring 规则（均标注TODO remove），即这些历史模块暂不强制 docstring，但新增代码应主动遵循规范。这与文档站使用 napoleon 扩展解析 Google 风格 docstring 的做法（见 docs/conf.py 的sphinx.ext.napoleon）前后呼应。

五、构建文档：从环境准备到本地预览

Gymnasium 的文档站基于 Sphinx 构建，包含大量自动生成的页面。CONTRIBUTING.md 给出的完整流程如下。

第 1 步：安装依赖

cd docs pip install -r requirements.txt

docs/requirements.txt 中包含的依赖说明了文档系统的组成：

sphinx、sphinx-autobuild：核心文档生成器与自动重载工具；
myst-parser：支持 Markdown（MyST）语法；
sphinx-gallery：生成教程/示例画廊；
celshast：用于生成教程文档的自定义扩展；
sphinx_github_changelog：从 GitHub 生成更新日志页面；
moviepy、pygame：用于渲染和录制环境演示视频/GIF；
ale_py：Atari 环境库（环境文档页需要导入环境以读取 docstring 与空间信息）；
tabulate：格式化表格输出。

第 2 步：生成环境文档并构建

python _scripts/gen_mds.py make dirhtml

gen_mds.py是文档管线的前置生成器：它遍历gymnasium.registry中的所有环境，排除GymV21Environment、FrozenLake8x8、BipedalWalkerHardcore、phys2d/*、tabular/*等重复或实验性条目，为每个环境找到最高版本号，调用gym.make实例化环境，从env.unwrapped.__doc__提取环境 docstring，再连同 Action Space、Observation Space、gymnasium.make(...)导入方式一起写入docs/environments/<模块>/<snake_name>.md（即 docs/environments/ 目录下各环境页面）。因此修改环境 docstring 后必须重新运行该脚本，环境文档页才会同步更新。

之后make dirhtml调用 docs/Makefile 中定义的sphinx-build，以docs/为源码目录、_build为输出目录构建 dirhtml 格式。构建配置集中在 docs/conf.py：它注册了sphinx.ext.napoleon（Google 风格 docstring 渲染）、sphinx.ext.autodoc（API 自动文档）、myst_parser（MyST Markdown 支持）、sphinx_gallery（教程画廊）、celshast.gen_tutorials（教程生成）等扩展，并从gymnasium.__version__动态读取release版本号。

第 3 步：本地预览

# 导航到 _build/dirhtml 目录 cd _build/dirhtml

然后在浏览器中打开index.html即可浏览本地文档站。_build目录由 docs/Makefile 的BUILDDIR = _build指定。

文档构建与贡献规范的联动

文档改进是官方接受的贡献类型之一，而文档构建管线对内容有硬性要求：gen_mds.py会对每个环境执行assert env_docstring——任何环境若缺少 docstring，生成脚本会直接断言失败。这从工具层面强制了"新代码必须写 docstring"的规范，也与第四节所述 pydocstyle 校验形成双重保障。

六、一份可执行的本地开发清单

综合全文，向 Gymnasium 提交贡献的推荐工作流如下：

安装pre-commit并执行pre-commit install，让每次提交自动触发 .pre-commit-config.yaml 定义的全部 Hooks；
提交前手动运行pre-commit run --all-files，按需迭代数次直至全部通过（格式化工具首轮会先改写代码）；
用ty check .单独验证类型检查，必要时在 pyproject.toml 的[tool.ty.src]中调整包含/排除范围；
为新增函数、类和文件编写 Google 风格 docstring，用pydocstyle --source --explain --convention=google自查；
在仓库根目录运行pytest跑完整测试套件；若改动涉及 doctest，追加pytest --doctest-modules --doctest-continue-on-failure gymnasium；
若改动涉及环境 docstring 或文档内容，在docs/下依次执行pip install -r requirements.txt、python _scripts/gen_mds.py、make dirhtml，然后在docs/_build/dirhtml/index.html中预览最终效果。

牢记贡献边界：只提交 Bug 修复、文档改进与新功能；不要提交新环境；任何涉及环境行为的修改都应尽量最小化，以保证不同版本间强化学习实验结果的可比性。

参考文件索引

贡献规范原文：CONTRIBUTING.md
工具链与规则配置：pyproject.toml
pre-commit Hooks 定义：.pre-commit-config.yaml
文档构建配置：docs/conf.py、docs/Makefile、docs/requirements.txt
环境文档自动生成脚本：docs/_scripts/gen_mds.py
环境文档输出目录：docs/environments/
测试套件入口：tests/test_core.py 与 tests/ 目录

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析