Update the documentation related to the Scenario Description (SD); bu…

…g fixes in SD and pull_assets (#605)

* improve language

* improve

* improve

* WIP the scenario description

* WIP

* update many docs

* add unittest to deal with the moving distance issue

* My test result is 1500 FPS

* Update SD

* add docs

* add test

* Finish

* format

* update

* typo

* finish

* finish

* fix typo

* fix typo

* try to fix bug

* fix

* raise error if can't find asset version file

* add debug msg

* try to fix a bug

* optimize the lock in pull_assets

* add lock to get asset version

* add lock to get asset version

* fix

* fix

* fix

* remove debug

.github/workflows/main.yml

@@ -74,9 +74,6 @@ jobs:
               body: `${{env.ROBOTMSG}}`
             })
 
-
-
-
   test_functionality:
     runs-on: ubuntu-latest
     steps:

documentation/README.md

@@ -4,7 +4,7 @@ documentation: [https://metadrive-simulator.readthedocs.io/](https://metadrive-s
 To build documents locally, please run the following codes:
 
 ```bash
-pip install sphinx sphinx_rtd_theme mst-nb
+pip install sphinx sphinx_rtd_theme myst-nb
 pip install sphinx-copybutton
 cd metadrive/documentation
 rm -rf build/ && make html
@@ -19,7 +19,7 @@ This tool can only check some external links. For checking cross-reference, usin
 
 ### How to reference a section of an `.ipynb` file in an RST file?
 
-Supposing you want to reference a section called TopDwnObservation in obs_action.ipynb, use
+Supposing you want to reference a section called `TopDwnObservation` in `obs_action.ipynb`, use
 
 ```
 `TopDownObservation <obs_action.html#topdownobservation>`_

documentation/source/debug_mode.ipynb

@@ -6,7 +6,7 @@
    "metadata": {},
    "source": [
     "# Debugging mode\n",
-    "There are several configurations can be turned on to debug the simulator. As a result, you can get more console output from the simulation and visualizations such as coordinates and physics to help develop features or fix bugs. To receive debug messages, set `debug=True` in the config used to create the environment. In debug mode, the `log_level` will be changed to `logging.DEBUG`, so you will get more information from MetaDrive, Panda3D, and RenderPipeline."
+    "Some configurations can be turned on to debug the simulator. As a result, you can get more console output from the simulation and visualizations such as coordinates and physics to help develop features or fix bugs. To receive debug messages, set `debug=True` in the config when creating the environment. In debug mode, the `log_level` will be changed to `logging.DEBUG`, so you will get more information from MetaDrive, Panda3D, and RenderPipeline in the console."
    ]
   },
   {
@@ -18,7 +18,7 @@
     "\n",
     "<img src=\"figs/debug_physics.png\" width=\"600\" class=\"center\">\n",
     "\n",
-    "It is important to making sure that physics world is accurate. For example, objects need bounding box to collide with each other. Specifying `debug=True` in environment config can turn on the debug mode. In this mode, you can visualize the physics world by pressing `1` (the one near `~`) on your keyboard. In the following example, we automatically turn on the physics world visualizer for you. Pressing `1` can turn if off. "
+    "It is important to make sure that physics world is accurate. For example, objects should have accurate bounding boxes in order to ensure the collision detection is correct. Specifying `debug=True` in environment config can turn on the debug mode. In this mode, you can visualize the physics world by pressing `1` (the one near `~`) on your keyboard. In the following example, we have automatically turned on the physics world visualizer for you by `env.engine.toggleDebug()`. Pressing `1` can turn if off."
    ]
   },
   {
@@ -53,11 +53,11 @@
    "id": "a6b6365a",
    "metadata": {},
    "source": [
-    "The default debug mode only visualizes what we called `dynamics physics world`. In this world, objects can have interactions conforming the physics law like collision, friction, and gravity. Actually, there is another physics world called `static physics world` where objects won't participate in collision and enjoy zero gravity. However, one can still query this world to know if an object in `dynamics physics world` has contact with objects in the `static physics world`. Thus we usually put objects like crosswalks, lane lines and lanes in this world. As a result, we can know which lane the car is on or if it is on a lane line or sidewalk, while keep the simulation at a high FPS as we only step the `dynamics physics world`.\n",
+    "The default debug mode only visualizes the object in the world called **\"dynamics physics world\"**. In this world, objects can have interactions following the physics law like collision, friction, and gravity. At the same time, there exists another physics world called **\"static physics world\"**, where objects won't participate in collision and enjoy zero gravity. However, one can still query this world to know if an object in dynamics physics world has contact with objects in the static physics world. Therefore, we usually put objects that are still like crosswalks, lane lines and lanes in this world. As a result, we can know which lane the car is on or if it is on a lane line or sidewalk, while keep the simulation at a high FPS as we only *step* the dynamics physics world.\n",
     "\n",
     "<img src=\"figs/debug_static.png\" width=\"600\">\n",
     "\n",
-    "To visualize the `dynamics physics world` and `static physics world` together, turn on the `debug_static_world`. The following example visualizes both physics worlds by adding objects which are supposed to be in `static physics world` to the `dynamics physics world`. You will also experience a FPS drop, which is why we separate the physics world into two."
+    "To visualize the dynamics physics world and static physics world together, we can turn on the `config['debug_static_world']=True`. The following example visualizes both physics worlds by adding objects which are supposed to be in static physics world to the dynamics physics world. You will also experience a FPS drop, which explains why we separate the physics world into two."
    ]
   },
   {
@@ -92,7 +92,7 @@
    "id": "688cfa36",
    "metadata": {},
    "source": [
-    "There is a more aggressive option `debug_physics_world` to debug the physics engine. It will turn off all graphics and only keep the line frames representing physics bodies. "
+    "There is a more aggressive option `debug_physics_world` to debug the physics engine. It will turn off all graphics and only keep the line frames representing physics bodies. Turn it on via `debug_physics_world=True`."
    ]
   },
   {

documentation/source/index.rst

@@ -15,7 +15,7 @@ Welcome to the MetaDrive documentation!
 MetaDrive is an efficient and compositional driving simulator with the following key features:
 
 * Compositional: It supports generating infinite scenes with various road maps and traffic settings for the research of generalizable RL.
-* Lightweight: It is easy to install and run. It can run up to 300 FPS on a standard PC.
+* Lightweight: It is easy to install and run. It can run up to 1,500 FPS on a standard PC.
 * Realistic: Accurate physics simulation and multiple sensory input including Lidar, RGB images, top-down semantic map and first-person view images.
 
 
@@ -59,7 +59,7 @@ Please feel free to contact us if you have any suggestions or ideas!
    panda_render.ipynb
    vehicle.ipynb
    navigation.ipynb
-   description.ipynb
+   scenario_description.ipynb
    record_replay.ipynb
    development.rst