2026/9/15 19:06:24
FEATURED · 精选文章 
Gymnasium 文档维护与构建指南从 docstring 自动生成环境文档到 Sphinx 站点发布【免费下载链接】GymnasiumA standard API for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)项目地址: https://gitcode.com/GitHub_Trending/gy/GymnasiumGymnasium前身为 OpenAI Gym的官方文档托管在docs/目录下采用 Sphinx MyST Markdown 构建。本文基于仓库中的 docs/README.md完整讲解如何修改环境文档页、如何新增环境文档、如何构建文档站点、如何编写教程四个核心流程并结合 docs/_scripts/ 下的生成脚本与 docs/conf.py 源码说明这些流程背后的自动化机制帮助维护者与贡献者快速上手 Gymnasium 文档工作流。文档目录结构与核心思想先概览docs/目录的职能分工目录/文件作用docs/environments/按环境类型如classic_control、box2d、mujoco、toy_text、atari存放自动生成的 Markdown 环境文档页docs/_scripts/文档自动化生成脚本gen_mds.py、gen_gifs.py、gen_wrapper_table.py等docs/_static/videos/各环境类型的演示 GIF如classic_control/cart_pole.gif、mujoco/half_cheetah.gifdocs/api/API 参考文档spaces、wrappers、vector、utils 等docs/tutorials/Sphinx-Gallery 教程源码.py文件docs/conf.pySphinx 构建配置文件docs/requirements.txt构建文档所需的 Python 依赖docs/Makefile/docs/make.batUnix / Windows 下的构建入口这套文档体系的核心设计思想是环境文档的单一事实来源是环境类自身的 docstring。修改环境行为或文档时只需编辑源码文件中的 docstring再运行生成脚本Markdown 页面即被自动重写从而保证源码与文档永不脱节。修改一个环境文档页docstring 即文档按 docs/README.md 的说明修改环境页面的标准流程为Fork Gymnasium在环境对应的 Python 文件中编辑其 docstring例如经典控制环境的源码位于 gymnasium/envs/classic_control/MuJoCo 环境位于 gymnasium/envs/mujoco/。安装你的 forkpip install gymnasium安装本地 fork 版本。运行生成脚本在仓库根目录执行docs/_scripts/gen_mds.py脚本会自动为环境生成对应的 Markdown 文档文件。gen_mds.py 的生成逻辑gen_mds.py 是整个流程的核心其工作步骤如下遍历gymnasium.registry即已注册的全部环境并排除一组不需要生成独立页面的环境包括GymV21Environment、GymV26Environment、CliffWalkingSlippery、FrozenLake8x8、LunarLanderContinuous、BipedalWalkerHardcore以及phys2d/、tabular/下的实验性环境。使用find_highest_version与get_env_id定义于 gymnasium/envs/registration.py为每个环境定位最高版本号并拼出规范 ID例如CartPole-v1。仅对entry_point字符串包含gymnasium的内置环境生成页面第三方注册的环境不会被打包进官方文档。实例化环境后通过env.unwrapped.__doc__取回 docstring经 utils.py 中的trim函数做规范化将制表符展开为空格、按最小缩进去除公共前导空白、剔除首尾空行。将环境的action_space与observation_space的repr压缩成单行连同gymnasium.make(env_id)一起写入页面顶部的 Action Space / Observation Space / import 表格。环境页面文件名由env_spec.name经 CamelCase 转 snake_case 得到如CartPole→cart_pole.md写入 docs/environments/{env_module}/ 对应子目录。生成的页面还带有autogenerated的 front-matter 标记并依据环境在排序后的位置自动添加firstpage:/lastpage:元信息供文档站点导航使用。每个环境页都通过figure指令引用docs/_static/videos/{env_module}/{snake_env_name}.gif作为预览图。添加一个新环境从注册到文档全流程若要在 Gymnasium或你的 fork中新增环境docs/README.md 给出了完整步骤。前置条件环境必须已加入 Gymnasium 的注册表位于 gymnasium/envs/init.py 或gymnasium.envs.registration的register调用。环境类的 Python 文件必须带有格式良好的 Markdown 风格 docstring——这是生成文档页面的唯一数据来源缺少 docstring 会导致gen_mds.py中的断言assert env_docstring失败。生成环境页面以可编辑模式安装你的 forkpip install -e .然后运行生成脚本docs/_scripts/gen_mds.py脚本会自动在docs/environments/{ENV_TYPE}/下生成该环境的.md页面例如docs/environments/mujoco/half_cheetah_v4.md。补充其他步骤添加演示 GIF将对应的 GIF 放入docs/_static/videos/{ENV_TYPE}目录ENV_TYPE为环境所属分类如mujoco、box2d文件名遵循 snake_case 命名规范。也可以直接运行docs/_scripts/gen_gifs.py自动录制。注册到导航树编辑docs/environments/{ENV_TYPE}/index.md把新环境对应的文件名加入toctree指令使其出现在文档导航中。gen_gifs.py 的录制原理gen_gifs.py 展示了 GIF 是如何自动录制的同样遍历注册表并复用find_highest_version/get_env_id定位最高版本跳过排除列表中的环境。仅处理render_modergb_array可用的环境通过env.metadata[render_modes]判断逐一收集帧。固定录制300 帧LENGTH 300先env.reset()循环内env.render()取帧、env.action_space.sample()随机动作推进环境遇到terminated or truncated则重新 reset。用 PIL 将帧序列保存为 GIF每帧时长duration50毫秒、loop0无限循环输出到docs/_static/videos/{env_module}/{snake_name}.gif。由此生成的环境预览图如下所示以classic_control的 CartPole 为例来自 docs/_static/videos/classic_control/cart_pole.gif其他配套自动化脚本docs/_scripts/下还提供了一批配套工具gen_wrapper_table.py遍历gymnasium.wrappers.__all__抓取每个 wrapper docstring 的第一行作为简介自动生成 docs/api/wrappers/table.md 中的 wrapper 总表含仅限 vector 使用的 wrapper 分表。gen_envs_display.py用于生成环境展示页的辅助脚本。linkcheck.py用于检查文档内部链接有效性的脚本。move_404.py用于站点 404 页面配置的脚本。构建文档站点安装依赖构建前需要安装 Gymnasium 本体以及docs/requirements.txt中列出的文档构建依赖pip install gymnasium pip install -r docs/requirements.txt从 docs/requirements.txt 可以看到构建栈的组成sphinx、sphinx-autobuild自动重构建、myst-parserMyST Markdown 解析、sphinx-gallery0.14.0教程构建、celshastFarama 定制的文档主题、moviepy与pygameGIF / 渲染相关、sphinx_github_changelog版本更新日志、ale_pyAtari与tabulate等。一次性构建在docs/目录下执行cd docs make dirhtmldirhtml是 Sphinx 的构建模式之一产物输出为docs/_build/dirhtml/每个页面生成一个独立目录。构建入口定义在 docs/Makefile它把目标透传给sphinx-build -M因此除dirhtml外也支持html、linkcheck、latexpdf等 Sphinx 标准目标。修改时自动重构建开发文档时使用sphinx-autobuild监听源码变化并实时刷新预览cd docs sphinx-autobuild -b dirhtml --watch ../gymnasium --re-ignore pickle$ . _build参数含义-b dirhtml指定与上面一致的dirhtml构建器--watch ../gymnasium额外监听仓库根目录下的gymnasium/源码包修改环境源码或 docstring 时也会触发重建--re-ignore pickle$忽略以pickle结尾的文件Sphinx-Gallery 缓存等避免不必要的重建. _build源目录为当前目录输出目录为_build。启动后浏览器访问 http://localhost:8000 即可实时查看更新后的文档。Windows 用户则可使用同目录下的 docs/make.bat例如make.bat dirhtml效果等价于make dirhtml。conf.py 构建配置要点docs/conf.py 是 Sphinx 配置的核心值得关注以下几点扩展列表启用sphinx.ext.napoleon解析 NumPy/Google 风格 docstring、sphinx.ext.autodoc自动文档、myst_parser、sphinx_gallery.gen_gallery教程构建、sphinx_github_changelog更新日志与 Farama 定制的celshast.gen_tutorials。Autodoc 定制通过remove_lines_before_parameters钩子在生成类文档时剔除__init__中位于第一个:param之前的重复描述避免与类 docstring 冗余。版本号release gymnasium.__version__从安装的包中动态读取版本。Sphinx-Gallery 配置sphinx_gallery_conf教程源目录为./tutorials忽略__init__.py并定义了两个教程分组的展示顺序——gymnasium_basicsenvironment_creation→implementing_custom_wrappers→handling_time_limits→load_quadruped_model与training_agentsblackjack_q_learning→frozenlake_q_learning→mujoco_reinforce→vector_a2c。主题html_theme celshast并配置了明暗双 Logo、html_title、html_baseurl等站点元信息。自动生成教程generate_tutorials(introduction/*.py, ./introduction)会把introduction目录下的教程也纳入自动生成流程。编写教程Sphinx-Gallery 工作流docs/tutorials目录下的教程由Sphinx-Gallery构建docs/conf.py 中的sphinx_gallery.gen_gallery扩展。Sphinx-Gallery 会读取每个.py教程文件逐段执行其中的代码块并把输出文本与 matplotlib 绘图自动嵌入生成的 HTML 页面。仓库中已内置两组可直接参考的教程源码基础篇 docs/tutorials/gymnasium_basics/如 environment_creation.py、implementing_custom_wrappers.py、handling_time_limits.py训练篇 docs/tutorials/training_agents/如 blackjack_q_learning.py、frozenlake_q_learning.py、mujoco_reinforce.py、vector_a2c.py。编写新教程时注意两个关键约定文件命名与执行如果希望 Sphinx-Gallery 在构建时真正执行教程代码并把输出、绘图结果写入页面文件名必须以run_开头。执行会显著增加构建耗时因此这类教程应控制运行时间在几秒以内。语法与示例教程文件遵循 Sphinx-Gallery 的文档字符串语法# %%分节、# sphinx_gallery_thumbnail_number缩略图选择等更多语法细节可查阅 Sphinx-Gallery 官方文档。若需要将 Jupyter Notebook 转为 Python 教程可使用社区提供的转换脚本转出的文件同样放入docs/tutorials后由 Sphinx-Gallery 统一处理。教程的最终导航层级由 docs/index.md 中的toctree组织tutorials/**/index使用 glob 模式自动收集所有教程子目录的索引页同时支持第三方教程入口 docs/tutorials/third-party-tutorials.md。总结一套源码驱动的文档自动化闭环综合 docs/README.md 与生成脚本源码Gymnasium 文档维护的核心闭环可概括为写源码环境 docstring 即文档正文wrapper 的 docstring 第一行即总表简介跑脚本gen_mds.py生成环境页、gen_wrapper_table.py生成 wrapper 总表、gen_gifs.py录制演示 GIF组导航在对应index.md的toctree中登记新页面构建发布make dirhtml一次性构建或sphinx-autobuild持续预览conf.py负责统一装配扩展、主题与教程。这套流程保证了改源码 docstring → 重新生成 → 文档同步更新让文档维护成本大幅降低也使得环境文档始终与最新代码保持严格一致。贡献者只需遵循上述约定即可在不接触构建细节的情况下完成文档的增改与发布。【免费下载链接】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 文档维护与构建指南：从 docstring 自动生成环境文档到 Sphinx 站点发布
Gymnasium 文档维护与构建指南从 docstring 自动生成环境文档到 Sphinx 站点发布【免费下载链接】GymnasiumA standard API for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym)项目地址: https://gitcode.com/GitHub_Trending/gy/GymnasiumGymnasium前身为 OpenAI Gym的官方文档托管在docs/目录下采用 Sphinx MyST Markdown 构建。本文基于仓库中的 docs/README.md完整讲解如何修改环境文档页、如何新增环境文档、如何构建文档站点、如何编写教程四个核心流程并结合 docs/_scripts/ 下的生成脚本与 docs/conf.py 源码说明这些流程背后的自动化机制帮助维护者与贡献者快速上手 Gymnasium 文档工作流。文档目录结构与核心思想先概览docs/目录的职能分工目录/文件作用docs/environments/按环境类型如classic_control、box2d、mujoco、toy_text、atari存放自动生成的 Markdown 环境文档页docs/_scripts/文档自动化生成脚本gen_mds.py、gen_gifs.py、gen_wrapper_table.py等docs/_static/videos/各环境类型的演示 GIF如classic_control/cart_pole.gif、mujoco/half_cheetah.gifdocs/api/API 参考文档spaces、wrappers、vector、utils 等docs/tutorials/Sphinx-Gallery 教程源码.py文件docs/conf.pySphinx 构建配置文件docs/requirements.txt构建文档所需的 Python 依赖docs/Makefile/docs/make.batUnix / Windows 下的构建入口这套文档体系的核心设计思想是环境文档的单一事实来源是环境类自身的 docstring。修改环境行为或文档时只需编辑源码文件中的 docstring再运行生成脚本Markdown 页面即被自动重写从而保证源码与文档永不脱节。修改一个环境文档页docstring 即文档按 docs/README.md 的说明修改环境页面的标准流程为Fork Gymnasium在环境对应的 Python 文件中编辑其 docstring例如经典控制环境的源码位于 gymnasium/envs/classic_control/MuJoCo 环境位于 gymnasium/envs/mujoco/。安装你的 forkpip install gymnasium安装本地 fork 版本。运行生成脚本在仓库根目录执行docs/_scripts/gen_mds.py脚本会自动为环境生成对应的 Markdown 文档文件。gen_mds.py 的生成逻辑gen_mds.py 是整个流程的核心其工作步骤如下遍历gymnasium.registry即已注册的全部环境并排除一组不需要生成独立页面的环境包括GymV21Environment、GymV26Environment、CliffWalkingSlippery、FrozenLake8x8、LunarLanderContinuous、BipedalWalkerHardcore以及phys2d/、tabular/下的实验性环境。使用find_highest_version与get_env_id定义于 gymnasium/envs/registration.py为每个环境定位最高版本号并拼出规范 ID例如CartPole-v1。仅对entry_point字符串包含gymnasium的内置环境生成页面第三方注册的环境不会被打包进官方文档。实例化环境后通过env.unwrapped.__doc__取回 docstring经 utils.py 中的trim函数做规范化将制表符展开为空格、按最小缩进去除公共前导空白、剔除首尾空行。将环境的action_space与observation_space的repr压缩成单行连同gymnasium.make(env_id)一起写入页面顶部的 Action Space / Observation Space / import 表格。环境页面文件名由env_spec.name经 CamelCase 转 snake_case 得到如CartPole→cart_pole.md写入 docs/environments/{env_module}/ 对应子目录。生成的页面还带有autogenerated的 front-matter 标记并依据环境在排序后的位置自动添加firstpage:/lastpage:元信息供文档站点导航使用。每个环境页都通过figure指令引用docs/_static/videos/{env_module}/{snake_env_name}.gif作为预览图。添加一个新环境从注册到文档全流程若要在 Gymnasium或你的 fork中新增环境docs/README.md 给出了完整步骤。前置条件环境必须已加入 Gymnasium 的注册表位于 gymnasium/envs/init.py 或gymnasium.envs.registration的register调用。环境类的 Python 文件必须带有格式良好的 Markdown 风格 docstring——这是生成文档页面的唯一数据来源缺少 docstring 会导致gen_mds.py中的断言assert env_docstring失败。生成环境页面以可编辑模式安装你的 forkpip install -e .然后运行生成脚本docs/_scripts/gen_mds.py脚本会自动在docs/environments/{ENV_TYPE}/下生成该环境的.md页面例如docs/environments/mujoco/half_cheetah_v4.md。补充其他步骤添加演示 GIF将对应的 GIF 放入docs/_static/videos/{ENV_TYPE}目录ENV_TYPE为环境所属分类如mujoco、box2d文件名遵循 snake_case 命名规范。也可以直接运行docs/_scripts/gen_gifs.py自动录制。注册到导航树编辑docs/environments/{ENV_TYPE}/index.md把新环境对应的文件名加入toctree指令使其出现在文档导航中。gen_gifs.py 的录制原理gen_gifs.py 展示了 GIF 是如何自动录制的同样遍历注册表并复用find_highest_version/get_env_id定位最高版本跳过排除列表中的环境。仅处理render_modergb_array可用的环境通过env.metadata[render_modes]判断逐一收集帧。固定录制300 帧LENGTH 300先env.reset()循环内env.render()取帧、env.action_space.sample()随机动作推进环境遇到terminated or truncated则重新 reset。用 PIL 将帧序列保存为 GIF每帧时长duration50毫秒、loop0无限循环输出到docs/_static/videos/{env_module}/{snake_name}.gif。由此生成的环境预览图如下所示以classic_control的 CartPole 为例来自 docs/_static/videos/classic_control/cart_pole.gif其他配套自动化脚本docs/_scripts/下还提供了一批配套工具gen_wrapper_table.py遍历gymnasium.wrappers.__all__抓取每个 wrapper docstring 的第一行作为简介自动生成 docs/api/wrappers/table.md 中的 wrapper 总表含仅限 vector 使用的 wrapper 分表。gen_envs_display.py用于生成环境展示页的辅助脚本。linkcheck.py用于检查文档内部链接有效性的脚本。move_404.py用于站点 404 页面配置的脚本。构建文档站点安装依赖构建前需要安装 Gymnasium 本体以及docs/requirements.txt中列出的文档构建依赖pip install gymnasium pip install -r docs/requirements.txt从 docs/requirements.txt 可以看到构建栈的组成sphinx、sphinx-autobuild自动重构建、myst-parserMyST Markdown 解析、sphinx-gallery0.14.0教程构建、celshastFarama 定制的文档主题、moviepy与pygameGIF / 渲染相关、sphinx_github_changelog版本更新日志、ale_pyAtari与tabulate等。一次性构建在docs/目录下执行cd docs make dirhtmldirhtml是 Sphinx 的构建模式之一产物输出为docs/_build/dirhtml/每个页面生成一个独立目录。构建入口定义在 docs/Makefile它把目标透传给sphinx-build -M因此除dirhtml外也支持html、linkcheck、latexpdf等 Sphinx 标准目标。修改时自动重构建开发文档时使用sphinx-autobuild监听源码变化并实时刷新预览cd docs sphinx-autobuild -b dirhtml --watch ../gymnasium --re-ignore pickle$ . _build参数含义-b dirhtml指定与上面一致的dirhtml构建器--watch ../gymnasium额外监听仓库根目录下的gymnasium/源码包修改环境源码或 docstring 时也会触发重建--re-ignore pickle$忽略以pickle结尾的文件Sphinx-Gallery 缓存等避免不必要的重建. _build源目录为当前目录输出目录为_build。启动后浏览器访问 http://localhost:8000 即可实时查看更新后的文档。Windows 用户则可使用同目录下的 docs/make.bat例如make.bat dirhtml效果等价于make dirhtml。conf.py 构建配置要点docs/conf.py 是 Sphinx 配置的核心值得关注以下几点扩展列表启用sphinx.ext.napoleon解析 NumPy/Google 风格 docstring、sphinx.ext.autodoc自动文档、myst_parser、sphinx_gallery.gen_gallery教程构建、sphinx_github_changelog更新日志与 Farama 定制的celshast.gen_tutorials。Autodoc 定制通过remove_lines_before_parameters钩子在生成类文档时剔除__init__中位于第一个:param之前的重复描述避免与类 docstring 冗余。版本号release gymnasium.__version__从安装的包中动态读取版本。Sphinx-Gallery 配置sphinx_gallery_conf教程源目录为./tutorials忽略__init__.py并定义了两个教程分组的展示顺序——gymnasium_basicsenvironment_creation→implementing_custom_wrappers→handling_time_limits→load_quadruped_model与training_agentsblackjack_q_learning→frozenlake_q_learning→mujoco_reinforce→vector_a2c。主题html_theme celshast并配置了明暗双 Logo、html_title、html_baseurl等站点元信息。自动生成教程generate_tutorials(introduction/*.py, ./introduction)会把introduction目录下的教程也纳入自动生成流程。编写教程Sphinx-Gallery 工作流docs/tutorials目录下的教程由Sphinx-Gallery构建docs/conf.py 中的sphinx_gallery.gen_gallery扩展。Sphinx-Gallery 会读取每个.py教程文件逐段执行其中的代码块并把输出文本与 matplotlib 绘图自动嵌入生成的 HTML 页面。仓库中已内置两组可直接参考的教程源码基础篇 docs/tutorials/gymnasium_basics/如 environment_creation.py、implementing_custom_wrappers.py、handling_time_limits.py训练篇 docs/tutorials/training_agents/如 blackjack_q_learning.py、frozenlake_q_learning.py、mujoco_reinforce.py、vector_a2c.py。编写新教程时注意两个关键约定文件命名与执行如果希望 Sphinx-Gallery 在构建时真正执行教程代码并把输出、绘图结果写入页面文件名必须以run_开头。执行会显著增加构建耗时因此这类教程应控制运行时间在几秒以内。语法与示例教程文件遵循 Sphinx-Gallery 的文档字符串语法# %%分节、# sphinx_gallery_thumbnail_number缩略图选择等更多语法细节可查阅 Sphinx-Gallery 官方文档。若需要将 Jupyter Notebook 转为 Python 教程可使用社区提供的转换脚本转出的文件同样放入docs/tutorials后由 Sphinx-Gallery 统一处理。教程的最终导航层级由 docs/index.md 中的toctree组织tutorials/**/index使用 glob 模式自动收集所有教程子目录的索引页同时支持第三方教程入口 docs/tutorials/third-party-tutorials.md。总结一套源码驱动的文档自动化闭环综合 docs/README.md 与生成脚本源码Gymnasium 文档维护的核心闭环可概括为写源码环境 docstring 即文档正文wrapper 的 docstring 第一行即总表简介跑脚本gen_mds.py生成环境页、gen_wrapper_table.py生成 wrapper 总表、gen_gifs.py录制演示 GIF组导航在对应index.md的toctree中登记新页面构建发布make dirhtml一次性构建或sphinx-autobuild持续预览conf.py负责统一装配扩展、主题与教程。这套流程保证了改源码 docstring → 重新生成 → 文档同步更新让文档维护成本大幅降低也使得环境文档始终与最新代码保持严格一致。贡献者只需遵循上述约定即可在不接触构建细节的情况下完成文档的增改与发布。【免费下载链接】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），仅供参考 
