Discussion: Changes to API Page

[Markus28]

I believe that the first code snippet in the "Interacting with the Environment" section of the API page is quite important because it serves to illustrates how gym is supposed to be used. I think there are a few changes that could make some points a bit clearer at a quick glance.

• The output of step should be assigned to variables with meaningful names
• Seeding should be demonstrated
• The environment should be reset after a done signal has been emitted

Therefore, I would suggest something like this:

import gym

env = gym.make("CartPole-v0")
env.seed(42)
observation = env.reset()

for _ in range(1000):
  env.render()
  observation, reward, done, info = env.step(env.action_space.sample())

  if done:
    observation = env.reset()
env.close()

This snippet would demonstrate all essential methods of the API.
Of course, the animation won't be as pretty as the current one, but I think this snippet would do a better job of illustrating the usage of gym.

I would also suggest that each method is covered in a small subsection that covers parameters, effects and return values.

One thing that was quite unclear to me when I started using gym was how to tell whether a done signal was generated by the environment or a time limit. This is quite important in many RL algorithms, e.g. SAC. Although one might cover this in the Wrappers section, I think it is worth mentioning in the API section as well.

[trigaten]

Can this be closed?

[Markus28]

Yes