- Resolve Sphinx build docs issue

- Remove 'actions' and 'behaviors' folders and import directly from the driving domain in metadrive model.
- Update documentation

.coveragerc

@@ -5,6 +5,7 @@ omit =
     src/scenic/simulators/carla/*
     src/scenic/simulators/gta/*
     src/scenic/simulators/lgsvl/*
+    src/scenic/simulators/metadrive/*
     src/scenic/simulators/webots/*
     src/scenic/simulators/xplane/*
 
@@ -26,4 +27,4 @@ exclude_lines =
 
 ignore_errors = True
 show_missing = True
-precision = 2
+precision = 2

codecov.yml

@@ -1,4 +1,4 @@
-codecov: 
+codecov:
   require_ci_to_pass: true
 
 coverage:
@@ -21,6 +21,7 @@ ignore:
   - "src/scenic/simulators/carla/"
   - "src/scenic/simulators/gta/"
   - "src/scenic/simulators/lgsvl/"
+  - "src/scenic/simulators/metadrive/"
   - "src/scenic/simulators/webots/"
   - "src/scenic/simulators/xplane/"
   - "!**/*.py"
@@ -30,4 +31,4 @@ comment:
 cli:
   plugins:
     pycoverage:
-      report_type: "json"
+      report_type: "json"

docs/simulators.rst

@@ -35,7 +35,7 @@ These issues are expected to be addressed in the next version of MetaDrive.
 
 Scenic uses OpenDRIVE maps, while MetaDrive relies on SUMO maps. Scenic provides corresponding SUMO maps for OpenDRIVE maps under the :file:`assets/maps/CARLA` directory.
 Additionally, you can convert your own OpenDRIVE maps to SUMO maps using the `netconvert <https://sumo.dlr.de/docs/Networks/Import/OpenDRIVE.html/>`_ tool.
-To avoid setting the SUMO map manually, name it the same as your OpenDRIVE file.
+To avoid setting the SUMO map manually, name it the same as your OpenDRIVE file and place it in the same directory.
 Otherwise, specify it explicitly with:
 
 .. code-block:: console

docs/tutorials/dynamics.rst

@@ -397,7 +397,7 @@ scenarios. We have examples written for the CARLA and LGSVL driving simulators,
 in :file:`examples/driving` in particular are designed to use Scenic's abstract
 :ref:`driving domain <driving_domain>` and so work in either of these simulators, as well
 as Scenic's built-in Newtonian physics simulator and MetaDrive simulator. While the Newtonian simulator is convenient
-for testing and simple experiments, we recommend using MetaDrive for more realistic driving scenarios.
+for testing simple experiments, we recommend using MetaDrive for more realistic driving scenarios.
 
 MetaDrive support is **optional**. If your system supports MetaDrive, you can install it separately using:
 

src/scenic/domains/driving/__init__.py

@@ -12,6 +12,7 @@
 Scenarios written for the driving domain should work without changes [#f1]_ in any of the
 following simulators:
 
+    * MetaDrive, using the model :doc:`scenic.simulators.metadrive.model`
     * CARLA, using the model :doc:`scenic.simulators.carla.model`
     * LGSVL, using the model :doc:`scenic.simulators.lgsvl.model`
     * the built-in Newtonian simulator, using the model
@@ -34,6 +35,14 @@
             $ scenic -S --model scenic.simulators.newtonian.driving_model \\
                 examples/driving/badlyParkedCarPullingIn.scenic
 
+    * MetaDrive, using the corresponding SUMO map (.net.xml) from the default map specified in
+      the scenario:
+
+        .. code-block:: console
+
+            $ scenic -S --2d --model scenic.simulators.metadrive.model \\
+                examples/driving/badlyParkedCarPullingIn.scenic
+
     * CARLA, using the default map specified in the scenario:
 
         .. code-block:: console

src/scenic/simulators/metadrive/__init__.py

@@ -1,8 +1,22 @@
+"""Interface to the MetaDrive driving simulator.
+
+This interface must currently be used in `2D compatibility mode`.
+
+It supports dynamic scenarios involving vehicles and pedestrians.
+
+The interface implements the :obj:`scenic.domains.driving` abstract domain, so any
+object types, behaviors, utility functions, etc. from that domain may be used freely.
+For details of additional MetaDrive-specific functionality, see the world model
+:obj:`scenic.simulators.metadrive.model`.
+"""
+
+# Only import MetaDriveSimulator if the metadrive package is installed; otherwise the
+# import would raise an exception.
+metadrive = None
 try:
     import metadrive
 except ImportError:
-    raise ImportError(
-        "Metadrive is required. Please install the 'metadrive' package (and sumolib) or use scenic[metadrive]."
-    )
-
-from .simulator import MetaDriveSimulator
+    pass
+if metadrive:
+    from .simulator import MetaDriveSimulator
+del metadrive

src/scenic/simulators/metadrive/model.scenic

@@ -24,14 +24,31 @@ Global Parameters:
         to process each step.
 """
 import pathlib
+
 from scenic.domains.driving.model import *
-from scenic.core.errors import InvalidScenarioError
+from scenic.domains.driving.actions import *
+from scenic.domains.driving.behaviors import *
 
-from scenic.simulators.metadrive.simulator import MetaDriveSimulator
-from scenic.simulators.metadrive.actions import *
-from scenic.simulators.metadrive.behaviors import *
-from scenic.simulators.metadrive.utils import scenicToMetaDriveHeading
+from scenic.core.errors import InvalidScenarioError
 
+try:
+    from scenic.simulators.metadrive.simulator import MetaDriveSimulator
+    from scenic.simulators.metadrive.utils import scenicToMetaDriveHeading
+except ModuleNotFoundError:
+    # for convenience when testing without the metadrive package
+    from scenic.core.simulators import SimulatorInterfaceWarning
+    import warnings
+    warnings.warn('The "metadrive" package is not installed; '
+                  'will not be able to run dynamic simulations',
+                  SimulatorInterfaceWarning)
+
+    def MetaDriveSimulator(*args, **kwargs):
+        """Dummy simulator to allow compilation without the 'metadrive' package.
+
+        :meta private:
+        """
+        raise RuntimeError('the "metadrive" package is required to run simulations '
+                           'from this scenario')
 
 if globalParameters.get("sumo_map") is None:
     sumo_map_path = str(pathlib.Path(globalParameters.map).with_suffix(".net.xml"))

src/scenic/simulators/metadrive/simulator.py

@@ -5,20 +5,20 @@
     from metadrive.component.vehicle.vehicle_type import DefaultVehicle
 except ImportError as e:
     raise ModuleNotFoundError(
-        'Metadrive scenarios require the "metadrive" package'
+        "Metadrive is required. Please install the 'metadrive' package (and sumolib) or use scenic[metadrive]."
     ) from e
 
 import logging
 import sys
 import time
 
 from scenic.core.simulators import SimulationCreationError
+from scenic.domains.driving.actions import *
 from scenic.domains.driving.controllers import (
     PIDLateralController,
     PIDLongitudinalController,
 )
 from scenic.domains.driving.simulators import DrivingSimulation, DrivingSimulator
-from scenic.simulators.metadrive.actions import *
 import scenic.simulators.metadrive.utils as utils