Add Tutorials using sphinx-gallery and other template updates (#56)

docs/.gitignore

@@ -4,12 +4,15 @@ __pycache__
 build/
 _build/
 
+tutorials/*
+!tutorials/*.md
+!tutorials/*.py
+
 environments/**/list.html
 environments/**/complete_list.html
-
+environments/**/complete_list.md
 environments/box2d/*.md
 environments/classic_control/*.md
 environments/mujoco/*.md
 environments/third_party_environments/*.md
-environments/toy_text/*.md
+environments/toy_text/*.md
-environments/**/complete_list.md

docs/conf.py

@@ -15,8 +15,11 @@
 # sys.path.insert(0, os.path.abspath('.'))
 
 # -- Project information -----------------------------------------------------
+import os
 from typing import Any, Dict
 
+from furo import gen_tutorials
+
 import gymnasium
 
 project = "Gymnasium"
@@ -46,7 +49,7 @@ templates_path = ["_templates"]
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ["tutorials/demo.rst"]
 
 # Napoleon settings
 napoleon_use_ivar = True
@@ -71,6 +74,8 @@ html_theme_options = {
     "light_logo": "img/gymnasium_black.svg",
     "dark_logo": "img/gymnasium_white.svg",
     "gtag": "G-6H9C8TWXZ8",
+    "description": "A standard API for reinforcement learning and a diverse set of reference environments (formerly Gym)",
+    "image": "img/gymnasium-github.png",
 }
 html_context: Dict[str, Any] = {}
 html_context["conf_py_path"] = "/docs/"
@@ -82,3 +87,9 @@ html_context["slug"] = "gymnasium"
 
 html_static_path = ["_static"]
 html_css_files = []
+
+# -- Generate Tutorials -------------------------------------------------
+
+gen_tutorials.generate(
+    os.path.join(os.path.dirname(__file__), "tutorials"),
+)

docs/index.md

@@ -12,7 +12,8 @@ lastpage:
    :width: 500
 ```
 
-**Gymnasium is a maintained fork of OpenAI’s Gym library. 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, and has a [compatibility wrapper](content/gym_compatibility
+) for old Gym environments:**
 
 ```{code-block} python
 
@@ -62,11 +63,13 @@ environments/third_party_environments
 
 ```{toctree}
 :hidden:
+:glob:
 :caption: Tutorials
 
 content/environment_creation
 content/vectorising
 content/handling_timelimits
+tutorials/*
 ```
 
 ```{toctree}

docs/requirements.txt

@@ -1,5 +1,6 @@
 sphinx
 myst-parser
+sphinx_gallery
 git+https://github.com/Farama-Foundation/Celshast#egg=furo
 moviepy
 pygame

docs/scripts/gen_envs_display.py

@@ -162,7 +162,7 @@ if __name__ == "__main__":
         type_id = type_dict["id"]
         envs_path = f"../environments/{type_id}"
         if len(type_dict["list"]) > 20:
-            page = generate_page(type_dict, limit=9)
+            page = generate_page(type_dict, limit=8)
             fp = open(
                 os.path.join(os.path.dirname(__file__), envs_path, "list.html"),
                 "w",

docs/tutorials/demo.py

@@ -0,0 +1,29 @@
+"""
+Demo tutorial script
+=========================
+
+This file is not listed in the website and serves only to give an example of a tutorial file. And is mostly a copy-paste from sphinx-gallery.
+"""
+
+# %%
+# This is a section header
+# ------------------------
+# This is the first section!
+# The `#%%` signifies to Sphinx-Gallery that this text should be rendered as
+# rST and if using one of the above IDE/plugin's, also signifies the start of a
+# 'code block'.
+
+# This line won't be rendered as rST because there's a space after the last block.
+myvariable = 2
+print(f"my variable is {myvariable}")
+# This is the end of the 'code block' (if using an above IDE). All code within
+# this block can be easily executed all at once.
+
+# %%
+# This is another section header
+# ------------------------------
+#
+# In the built documentation, it will be rendered as rST after the code above!
+# This is also another code block.
+
+print(f"my variable plus 2 is {myvariable + 2}")