diff --git a/docs/README.md b/docs/README.md index 5ab924fb2..a4c491171 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Gymnasium-docs -This folder contains the documentation for [Gymnasium](https://github.com/Farama-Foundation/gymnasium). +This folder contains the documentation for [Gymnasium](https://github.com/Farama-Foundation/Gymnasium). If you are modifying a non-environment page or an atari environment page, please PR this repo. Otherwise, follow the steps below: diff --git a/docs/api/spaces.md b/docs/api/spaces.md index cd332aa2c..ee258b05c 100644 --- a/docs/api/spaces.md +++ b/docs/api/spaces.md @@ -1,5 +1,13 @@ # Spaces +```{toctree} +:hidden: +spaces/fundamental +spaces/composite +spaces/utils +``` + + ```{eval-rst} .. autoclass:: gymnasium.spaces.Space ``` @@ -28,77 +36,30 @@ Each space implements the following functions: ## Fundamental Spaces -### Box - ```{eval-rst} -.. autoclass:: gymnasium.spaces.Box +.. currentmodule:: gymnasium.spaces - .. automethod:: is_bounded - .. automethod:: sample -``` - -### Discrete - -```{eval-rst} -.. autoclass:: gymnasium.spaces.Discrete - - .. automethod:: sample -``` - -### MultiBinary - -```{eval-rst} -.. autoclass:: gymnasium.spaces.MultiBinary - - .. automethod:: sample -``` - -### MultiDiscrete - -```{eval-rst} -.. autoclass:: gymnasium.spaces.MultiDiscrete - - .. automethod:: sample -``` - -### Text - -```{eval-rst} -.. autoclass:: gymnasium.spaces.Text - - .. automethod:: sample -``` +* :py:class:`Box` - Supports continuous (and discrete) vectors or matrices, used for vector observations, images, etc +* :py:class:`Discrete` - Supports a single discrete number of values with an optional start for the values +* :py:class:`MultiDiscrete` - Supports single or matrices of binary values, used for holding down a button or if an agent has an object +* :py:class:`MultiBinary` - Supports multiple discrete values with multiple axes, used for controller actions +* :py:class:`Text` - Supports strings, used for passing agent messages, mission details, etc +``` ## Composite Spaces -### Dict - ```{eval-rst} -.. autoclass:: gymnasium.spaces.Dict - - .. automethod:: sample -``` - -### Graph - -```{eval-rst} -.. autoclass:: gymnasium.spaces.Graph - - .. automethod:: sample +* :py:class:`Dict` - Supports a dictionary of keys and subspaces, used for a fixed number of unordered spaces +* :py:class:`Tuple` - Supports a tuple of subspaces, used for multiple for a fixed number of ordered spaces +* :py:class:`Sequence` - Supports a variable number of instances of a single subspace, used for entities spaces or selecting a variable number of actions +* :py:class:`Graph` - Supports graph based actions or observations with discrete or continuous nodes and edge values. ``` -### Sequence +## Utils ```{eval-rst} -.. autoclass:: gymnasium.spaces.Sequence - - .. automethod:: sample -``` - -### Tuple - -```{eval-rst} -.. autoclass:: gymnasium.spaces.Tuple - - .. automethod:: sample -``` +* :py:class:`utils.flatdim` - The number of dimensions the flattened space will contain +* :py:class:`utils.flatten_space` - Flattens a space for which the `flattened` space instances will contain +* :py:class:`utils.flatten` - Flattens an instance of a space that is contained within the flattened version of the space +* :py:class:`utils.unflatten` - The reverse of the `flatten_space` function +``` diff --git a/docs/api/spaces/composite.md b/docs/api/spaces/composite.md new file mode 100644 index 000000000..b93d0b722 --- /dev/null +++ b/docs/api/spaces/composite.md @@ -0,0 +1,33 @@ +# Composite Spaces + +## Dict + +```{eval-rst} +.. autoclass:: gymnasium.spaces.Dict + + .. automethod:: sample +``` + +## Tuple + +```{eval-rst} +.. autoclass:: gymnasium.spaces.Tuple + + .. automethod:: sample +``` + +## Sequence + +```{eval-rst} +.. autoclass:: gymnasium.spaces.Sequence + + .. automethod:: sample +``` + +## Graph + +```{eval-rst} +.. autoclass:: gymnasium.spaces.Graph + + .. automethod:: sample +``` diff --git a/docs/api/spaces/fundamental.md b/docs/api/spaces/fundamental.md new file mode 100644 index 000000000..4eab2310c --- /dev/null +++ b/docs/api/spaces/fundamental.md @@ -0,0 +1,46 @@ +--- +title: Fundamental Spaces +--- + +# Fundamental Spaces + +## Box + +```{eval-rst} +.. autoclass:: gymnasium.spaces.Box + + .. automethod:: is_bounded + .. automethod:: sample +``` + +## Discrete + +```{eval-rst} +.. autoclass:: gymnasium.spaces.Discrete + + .. automethod:: sample +``` + +## MultiBinary + +```{eval-rst} +.. autoclass:: gymnasium.spaces.MultiBinary + + .. automethod:: sample +``` + +## MultiDiscrete + +```{eval-rst} +.. autoclass:: gymnasium.spaces.MultiDiscrete + + .. automethod:: sample +``` + +## Text + +```{eval-rst} +.. autoclass:: gymnasium.spaces.Text + + .. automethod:: sample +``` \ No newline at end of file diff --git a/docs/api/spaces_utils.md b/docs/api/spaces/utils.md similarity index 100% rename from docs/api/spaces_utils.md rename to docs/api/spaces/utils.md diff --git a/docs/api/wrappers.md b/docs/api/wrappers.md index bc6f7c427..6dbb8edee 100644 --- a/docs/api/wrappers.md +++ b/docs/api/wrappers.md @@ -51,7 +51,7 @@ There are three common things you might want a wrapper to do: Such wrappers can be easily implemented by inheriting from `ActionWrapper`, `ObservationWrapper`, or `RewardWrapper` and implementing the respective transformation. If you need a wrapper to do more complicated tasks, you can inherit from the `Wrapper` class directly. The code that is presented in the following sections can also be found in -the [gymnasium-examples](https://github.com/Farama-Foundation/gymnasium-examples) repository +the [gym-examples](https://github.com/Farama-Foundation/gym-examples) repository ## ActionWrapper If you would like to apply a function to the action before passing it to the base environment, diff --git a/docs/content/environment_creation.md b/docs/content/environment_creation.md index 9f05cd96e..cfd2be172 100644 --- a/docs/content/environment_creation.md +++ b/docs/content/environment_creation.md @@ -17,7 +17,7 @@ pip install -e . ## Subclassing gymnasium.Env -Before learning how to create your own environment you should check out [the documentation of Gymnasium's API](https://gymnasium.farama.org/content/api/). +Before learning how to create your own environment you should check out [the documentation of Gymnasium's API](/api/core). We will be concerned with a subset of gym-examples that looks like this: @@ -56,7 +56,7 @@ where the blue dot is the agent and the red square represents the target. Let us look at the source code of `GridWorldEnv` piece by piece: ### Declaration and Initialization -Our custom environment will inherit from the abstract class `gymnasium.Env`. You shouldn't forget to add the `metadata` attribute to you class. +Our custom environment will inherit from the abstract class `gymnasium.Env`. You shouldn't forget to add the `metadata` attribute to your class. There, you should specify the render-modes that are supported by your environment (e.g. `"human"`, `"rgb_array"`, `"ansi"`) and the framerate at which your environment should be rendered. Every environment should support`None` as render-mode; you don't need to add it in the metadata. In `GridWorldEnv`, we will support the modes "rgb_array" and "human" and render at 4 FPS. @@ -307,7 +307,7 @@ register( The environment ID consists of three components, two of which are optional: an optional namespace (here: `gym_examples`), a mandatory name (here: `GridWorld`) and an optional but recommended version (here: v0). It might have also been registered as `GridWorld-v0` (the recommended approach), `GridWorld` or `gym_examples/GridWorld`, and the appropriate ID should then be used during environment creation. The keyword argument `max_episode_steps=300` will ensure that GridWorld environments that are instantiated via `gymnasium.make` -will be wrapped in a `TimeLimit` wrapper (see [the wrapper documentation](https://www.gymlibrary.dev/pages/wrappers/index) +will be wrapped in a `TimeLimit` wrapper (see [the wrapper documentation](/api/wrappers) for more information). A done signal will then be produced if the agent has reached the target *or* 300 steps have been executed in the current episode. To distinguish truncation and termination, you can check `info["TimeLimit.truncated"]`. @@ -372,7 +372,7 @@ also perfectly fine (but remember to add wrappers as well!). Oftentimes, we want to use different variants of a custom environment, or we want to modify the behavior of an environment that is provided by Gymnasium or some other party. Wrappers allow us to do this without changing the environment implementation or adding any boilerplate code. -Check out the [wrapper documentation](https://www.gymlibrary.dev/content/wrappers/) for details on how to +Check out the [wrapper documentation](/api/wrappers/) for details on how to use wrappers and instructions for implementing your own. In our example, observations cannot be used directly in learning code because they are dictionaries. However, we don't actually need to touch our environment implementation to fix this! We can simply add @@ -389,7 +389,7 @@ print(wrapped_env.reset()) # E.g. [3 0 3 3], {} Wrappers have the big advantage that they make environments highly modular. For instance, instead of flattening the observations from GridWorld, you might only want to look at the relative position of the target and the agent. -In the section on [ObservationWrappers](https://www.gymlibrary.dev/content/wrappers/#observationwrapper) we have implemented +In the section on [ObservationWrappers](/api/wrappers/#observationwrapper) we have implemented a wrapper that does this job. This wrapper is also available in gym-examples: ```python diff --git a/docs/index.md b/docs/index.md index f6d007db7..7f0c60cd5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ lastpage: :width: 500 ``` -**The Gymnasium interface is simple, pythonic, and capable of representing general RL problems:** +**Gymnasium is a maintained fork of OpenAI’s Gym library. The Gymnasium interface is simple, pythonic, and capable of representing general RL problems:** ```{code-block} python @@ -41,7 +41,6 @@ content/basic_usage api/core api/spaces -api/spaces_utils api/wrappers api/vector api/utils @@ -71,7 +70,7 @@ content/vectorising :hidden: :caption: Development -Github +Github Donate ``` diff --git a/gymnasium/utils/env_checker.py b/gymnasium/utils/env_checker.py index 5cef06b97..78a75d19b 100644 --- a/gymnasium/utils/env_checker.py +++ b/gymnasium/utils/env_checker.py @@ -258,7 +258,7 @@ def check_env(env: gymnasium.Env, warn: bool = None, skip_render_check: bool = F This is an invasive function that calls the environment's reset and step. This is particularly useful when using a custom environment. - Please take a look at https://www.gymlibrary.dev/content/environment_creation/ + Please take a look at https://gymnasium.farama.org/content/environment_creation/ for more information about the API. Args: @@ -271,7 +271,7 @@ def check_env(env: gymnasium.Env, warn: bool = None, skip_render_check: bool = F assert isinstance( env, gymnasium.Env - ), "The environment must inherit from the gymnasium.Env class. See https://www.gymlibrary.dev/content/environment_creation/ for more info." + ), "The environment must inherit from the gymnasium.Env class. See https://gymnasium.farama.org/content/environment_creation/ for more info." if env.unwrapped is not env: logger.warn( @@ -281,13 +281,13 @@ def check_env(env: gymnasium.Env, warn: bool = None, skip_render_check: bool = F # ============= Check the spaces (observation and action) ================ assert hasattr( env, "action_space" - ), "The environment must specify an action space. See https://www.gymlibrary.dev/content/environment_creation/ for more info." + ), "The environment must specify an action space. See https://gymnasium.farama.org/content/environment_creation/ for more info." check_action_space(env.action_space) check_space_limit(env.action_space, "action") assert hasattr( env, "observation_space" - ), "The environment must specify an observation space. See https://www.gymlibrary.dev/content/environment_creation/ for more info." + ), "The environment must specify an observation space. See https://gymnasium.farama.org/content/environment_creation/ for more info." check_observation_space(env.observation_space) check_space_limit(env.observation_space, "observation") diff --git a/gymnasium/wrappers/env_checker.py b/gymnasium/wrappers/env_checker.py index 142d22e1e..6df4e2798 100644 --- a/gymnasium/wrappers/env_checker.py +++ b/gymnasium/wrappers/env_checker.py @@ -19,11 +19,11 @@ class PassiveEnvChecker(gymnasium.Wrapper): assert hasattr( env, "action_space" - ), "The environment must specify an action space. https://www.gymlibrary.dev/content/environment_creation/" + ), "The environment must specify an action space. https://gymnasium.farama.org/content/environment_creation/" check_action_space(env.action_space) assert hasattr( env, "observation_space" - ), "The environment must specify an observation space. https://www.gymlibrary.dev/content/environment_creation/" + ), "The environment must specify an observation space. https://gymnasium.farama.org/content/environment_creation/" check_observation_space(env.observation_space) self.checked_reset = False diff --git a/setup.py b/setup.py index a4d2c2a17..6433d1081 100644 --- a/setup.py +++ b/setup.py @@ -86,7 +86,7 @@ setup( }, python_requires=">=3.6", tests_require=extras["testing"], - url="https://www.gymlibrary.dev/", + url="https://gymnasium.farama.org/", version=VERSION, zip_safe=False, ) diff --git a/tests/utils/test_env_checker.py b/tests/utils/test_env_checker.py index 8ae2d490c..3cee0c742 100644 --- a/tests/utils/test_env_checker.py +++ b/tests/utils/test_env_checker.py @@ -244,15 +244,15 @@ def test_check_reset_options(): [ [ "Error", - "The environment must inherit from the gymnasium.Env class. See https://www.gymlibrary.dev/content/environment_creation/ for more info.", + "The environment must inherit from the gymnasium.Env class. See https://gymnasium.farama.org/content/environment_creation/ for more info.", ], [ GenericTestEnv(action_space=None), - "The environment must specify an action space. See https://www.gymlibrary.dev/content/environment_creation/ for more info.", + "The environment must specify an action space. See https://gymnasium.farama.org/content/environment_creation/ for more info.", ], [ GenericTestEnv(observation_space=None), - "The environment must specify an observation space. See https://www.gymlibrary.dev/content/environment_creation/ for more info.", + "The environment must specify an observation space. See https://gymnasium.farama.org/content/environment_creation/ for more info.", ], ], ) diff --git a/tests/wrappers/test_passive_env_checker.py b/tests/wrappers/test_passive_env_checker.py index 6d6284685..1d5d3be07 100644 --- a/tests/wrappers/test_passive_env_checker.py +++ b/tests/wrappers/test_passive_env_checker.py @@ -35,7 +35,7 @@ def test_passive_checker_wrapper_warnings(env): [ ( GenericTestEnv(action_space=None), - "The environment must specify an action space. https://www.gymlibrary.dev/content/environment_creation/", + "The environment must specify an action space. https://gymnasium.farama.org/content/environment_creation/", ), ( GenericTestEnv(action_space="error"), @@ -43,7 +43,7 @@ def test_passive_checker_wrapper_warnings(env): ), ( GenericTestEnv(observation_space=None), - "The environment must specify an observation space. https://www.gymlibrary.dev/content/environment_creation/", + "The environment must specify an observation space. https://gymnasium.farama.org/content/environment_creation/", ), ( GenericTestEnv(observation_space="error"),