Skip to content

Commit 9e2b3cb

Browse files
Improve the tutorial rendering (#1353)
1 parent 8d5fd4f commit 9e2b3cb

12 files changed

+49
-40
lines changed

docs/conf.py

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@
1212

1313
# -- Project information -----------------------------------------------------
1414
import os
15-
import re
1615
import sys
1716
import time
1817

1918
import sphinx_gallery.gen_rst
19+
import sphinx_gallery.sorting
2020
from furo.gen_tutorials import generate_tutorials
2121

2222

@@ -123,10 +123,30 @@ def setup(app):
123123
124124
.. rst-class:: sphx-glr-example-title
125125
126+
.. note::
127+
This example is compatible with Gymnasium version |release|.
128+
126129
.. _sphx_glr_{1}:
127130
128131
"""
129132

133+
tutorial_sorting = {
134+
"tutorials/gymnasium_basics": [
135+
"environment_creation",
136+
"implementing_custom_wrappers",
137+
"handling_time_limits",
138+
"load_quadruped_model",
139+
"*",
140+
],
141+
"tutorials/training_agents": [
142+
"blackjack_q_learning",
143+
"frozenlake_q_learning",
144+
"mujoco_reinforce",
145+
"vector_a2c",
146+
"*",
147+
],
148+
}
149+
130150
sphinx_gallery_conf = {
131151
"ignore_pattern": r"__init__\.py",
132152
"examples_dirs": "./tutorials",
@@ -135,10 +155,13 @@ def setup(app):
135155
"show_signature": False,
136156
"show_memory": False,
137157
"min_reported_time": float("inf"),
138-
"filename_pattern": f"{re.escape(os.sep)}run_",
158+
# "filename_pattern": f"{re.escape(os.sep)}run_",
139159
"default_thumb_file": os.path.join(
140160
os.path.dirname(__file__), "_static/img/gymnasium-github.png"
141161
),
162+
# order the tutorial presentation order
163+
"within_subsection_order": sphinx_gallery.sorting.FileNameSortKey,
164+
"subsection_order": lambda folder: tutorial_sorting[folder],
142165
}
143166

144167
# All tutorials in the tutorials directory will be generated automatically

docs/tutorials/README.rst

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,2 @@
11
Tutorials
22
=========
3-
4-
We provide two sets of tutorials: basics and training.
5-
6-
* The aim of the basics tutorials is to showcase the fundamental API of Gymnasium to help users implement it
7-
* The most common application of Gymnasium is for training RL agents, the training tutorials aim to show a range of example implementations for different environments
8-
9-
Additionally, we provide the third party tutorials as a link for external projects that utilise Gymnasium that could help users.
Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
Gymnasium Basics
2-
----------------
2+
================
33

4-
.. toctree::
5-
:hidden:
4+
.. _gallery_section_name:
65

7-
environment_creation
8-
implementing_custom_wrappers
9-
handling_time_limits
10-
load_quadruped_model
6+
The aim of these tutorials is to showcase the fundamental API of Gymnasium to help users implement it

docs/tutorials/gymnasium_basics/environment_creation.py

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,7 @@
33
Make your own custom environment
44
================================
55
6-
This documentation overviews creating new environments and relevant
7-
useful wrappers, utilities and tests included in Gymnasium designed for
8-
the creation of new environments.
9-
6+
This tutorial shows how to create new environment and links to relevant useful wrappers, utilities and tests included in Gymnasium.
107
118
Setup
129
------

docs/tutorials/gymnasium_basics/handling_time_limits.py

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@
22
Handling Time Limits
33
====================
44
5-
In using Gymnasium environments with reinforcement learning code, a common problem observed is how time limits are incorrectly handled. The ``done`` signal received (in previous versions of OpenAI Gym < 0.26) from ``env.step`` indicated whether an episode has ended. However, this signal did not distinguish whether the episode ended due to ``termination`` or ``truncation``.
5+
This tutorial explains how time limits should be correctly handled with `termination` and `truncation` signals.
6+
7+
The ``done`` signal received (in previous versions of OpenAI Gym < 0.26) from ``env.step`` indicated whether an episode has ended.
8+
However, this signal did not distinguish whether the episode ended due to ``termination`` or ``truncation``.
69
710
Termination
811
-----------

docs/tutorials/gymnasium_basics/implementing_custom_wrappers.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
============================
44
55
In this tutorial we will describe how to implement your own custom wrappers.
6+
67
Wrappers are a great way to add functionality to your environments in a modular way.
78
This will save you a lot of boilerplate code.
89

docs/tutorials/gymnasium_basics/load_quadruped_model.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,7 @@
22
Load custom quadruped robot environments
33
========================================
44
5-
In this tutorial we will see how to use the `MuJoCo/Ant-v5` framework to create a quadruped walking environment,
6-
using a model file (ending in `.xml`) without having to create a new class.
5+
In this tutorial create a mujoco quadruped walking environment using a model file (ending in `.xml`) without having to create a new class.
76
87
Steps:
98
Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
Training Agents
2-
---------------
2+
===============
33

4-
.. toctree::
5-
:hidden:
4+
.. _gallery_section_name:
65

7-
blackjack_q_learning
8-
frozenlake_q_learning
9-
mujoco_reinforce
10-
vector_a2c
6+
The most common application of Gymnasium is for training RL agents. Therefore, these tutorials aim to show a range of example implementations for different environments.

docs/tutorials/training_agents/blackjack_q_learning.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
"""
2-
Solving Blackjack with Q-Learning
3-
=================================
2+
Solving Blackjack with Tabular Q-Learning
3+
=========================================
44
5+
This tutorial trains an agent for BlackJack using tabular Q-learning.
56
"""
67

78
# %%

docs/tutorials/training_agents/frozenlake_q_learning.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
"""
2-
Frozenlake benchmark
3-
====================
2+
Solving Frozenlake with Tabular Q-Learning
3+
==========================================
44
5+
This tutorial trains an agent for FrozenLake using tabular Q-learning.
56
"""
67

78
# %%

0 commit comments

Comments
 (0)