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 RequestPull 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-filesty的配置存放位置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 规则选择为Epycodestyle 错误、Fpyflakes、UPpyupgrade、Iisort、Dpydocstyle、Bbugbear并忽略E501行长度。同时.pre-commit-config.yaml 中以注释形式保留了 flake8 与 pydocstyle 的旧配置说明项目经历过从 flake8/pydocstyle 到 ruff 的工具链迁移D规则由 ruff 内置的 pydocstyle 支持接管。Pull Request 的完整测试除了 pre-commitPR 还会针对整个项目运行基于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 --conventiongoogle当 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.txtdocs/requirements.txt 中包含的依赖说明了文档系统的组成sphinx、sphinx-autobuild核心文档生成器与自动重载工具myst-parser支持 MarkdownMyST语法sphinx-gallery生成教程/示例画廊celshast用于生成教程文档的自定义扩展sphinx_github_changelog从 GitHub 生成更新日志页面moviepy、pygame用于渲染和录制环境演示视频/GIFale_pyAtari 环境库环境文档页需要导入环境以读取 docstring 与空间信息tabulate格式化表格输出。第 2 步生成环境文档并构建python _scripts/gen_mds.py make dirhtmlgen_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.napoleonGoogle 风格 docstring 渲染、sphinx.ext.autodocAPI 自动文档、myst_parserMyST 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 --conventiongoogle自查在仓库根目录运行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.tomlpre-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/ 目录【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 RequestPull 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-filesty的配置存放位置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 规则选择为Epycodestyle 错误、Fpyflakes、UPpyupgrade、Iisort、Dpydocstyle、Bbugbear并忽略E501行长度。同时.pre-commit-config.yaml 中以注释形式保留了 flake8 与 pydocstyle 的旧配置说明项目经历过从 flake8/pydocstyle 到 ruff 的工具链迁移D规则由 ruff 内置的 pydocstyle 支持接管。Pull Request 的完整测试除了 pre-commitPR 还会针对整个项目运行基于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 --conventiongoogle当 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.txtdocs/requirements.txt 中包含的依赖说明了文档系统的组成sphinx、sphinx-autobuild核心文档生成器与自动重载工具myst-parser支持 MarkdownMyST语法sphinx-gallery生成教程/示例画廊celshast用于生成教程文档的自定义扩展sphinx_github_changelog从 GitHub 生成更新日志页面moviepy、pygame用于渲染和录制环境演示视频/GIFale_pyAtari 环境库环境文档页需要导入环境以读取 docstring 与空间信息tabulate格式化表格输出。第 2 步生成环境文档并构建python _scripts/gen_mds.py make dirhtmlgen_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.napoleonGoogle 风格 docstring 渲染、sphinx.ext.autodocAPI 自动文档、myst_parserMyST 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 --conventiongoogle自查在仓库根目录运行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.tomlpre-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/ 目录【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
