Update DOC

doc/source/conf.py

@@ -61,7 +61,16 @@ def __getattr__(cls, name):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'sphinx.ext.napoleon', 'myst_parser', 'sphinx_multiversion', 'sphinx_copybutton'
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'myst_parser', 'sphinx_multiversion', 'sphinx_copybutton'
+]
+
+myst_enable_extensions = [
+    "amsmath",
+    "deflist",
+    "html_admonition",
+    "html_image",
+    "colon_fence",
+    # Add other extensions as needed
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -90,6 +99,28 @@ def __getattr__(cls, name):
 
 autodoc_member_order = 'bysource'
 
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+# myst_enable_extensions = [
+#     "amsmath",
+#     "attrs_inline",
+#     "colon_fence",
+#     "deflist",
+#     "dollarmath",
+#     "fieldlist",
+#     "html_admonition",
+#     "html_image",
+#     "replacements",
+#     "smartquotes",
+#     "strikethrough",
+#     "substitution",
+#     "tasklist",
+# ]
+
+
 
 def setup(app):
     app.add_css_file('my_theme.css')

doc/source/configuration.md

@@ -41,11 +41,12 @@ obstacle:
     unobstructed: True
 ```
 
-**Note**:
+:::{Note}
   - To include several robots or obstacles in the configuration file, add separate entries under the robot and obstacle sections using `-` for each additional item.
   - Parameters such as distribution, shape, behavior, and kinematics must be formatted as `{key: value}` pairs. Ensure that each dictionary includes the `name` key; omitting name will result in a None value for that parameter.
   - When dealing with multiple objects (i.e., when the number is greater than 1), utilize the `distribution` parameter to define how these objects are distributed.
   - By default, all objects within the same group share identical configurations. To customize individual objects within a group, add sub-parameters using `-`. Any additional objects not explicitly configured will inherit the settings of the last specified object in the group.
+:::
 
 ## World Configuration
 
@@ -120,9 +121,10 @@ world:
   mdownsample: 2                      # Downsampling factor for the obstacle map
 ```
 
-**Notes:**
+:::{warning}
+**`obstacle_map`**: Replace `"path/to/map.png"` with the actual file path to your obstacle map image. Ensure that the image is in a compatible format (e.g., PNG, JPEG) and properly represents obstacle locations.
+:::
 
-- **`obstacle_map`**: Replace `"path/to/map.png"` with the actual file path to your obstacle map image. Ensure that the image is in a compatible format (e.g., PNG, JPEG) and properly represents obstacle locations.
 
 ## Object Configuration (Robot and Obstacle)
 
@@ -229,7 +231,9 @@ All `robot` and `obstacle` entities in the simulation are configured as objects
     kinematics: {name: 'acker', noise: True, alpha: [0.03, 0, 0, 0.03], mode: 'steer'}
     ```
 
-  **Note**: When using the `acker` kinematics model, ensure that the `wheelbase` parameter is set in the `shape` configuration.
+  :::{warning}
+    When using the `acker` kinematics model, ensure that the `wheelbase` parameter is set in the `shape` configuration.
+  :::
 
 - **`shape`**:
   Determines the geometric shape used for collision detection and visualization in the original state. Supported shapes and required parameters:
@@ -283,7 +287,7 @@ All `robot` and `obstacle` entities in the simulation are configured as objects
     - **`vertices`** (`list`): List of vertices defining the line string in the format `[[x1, y1], [x2, y2], ...]`.
     - **`random_shape`** (`bool`): Whether to generate a series of random line strings (polygon). Default is `False`.
     - **`is_convex`** (`bool`): Whether to generate a series of random convex line strings (polygons). Default is `False`.
-    - parameters for random line string generation (polygon), see [random_generate_polygon](https://ir-sim.readthedocs.io/en/latest/irsim.lib.html#module-irsim.lib.generation) for more details. Parameters include `number `, `center_range `, `avg_radius_range `, `irregularity_range `, `spikeyness_range `, `num_vertices_range `.
+    - parameters for random line string generation (polygon), see [random_generate_polygon](#irsim.lib.algorithm.generation.random_generate_polygon) for more details. Parameters include `number `, `center_range `, `avg_radius_range `, `irregularity_range `, `spikeyness_range `, `num_vertices_range `.
 
     **Example:**
     ```yaml
@@ -523,6 +527,10 @@ All `robot` and `obstacle` entities in the simulation are configured as objects
 
 ### Example Object Configurations
 
+:::{tip}
+Let's give readers a helpful hint!
+:::
+
 #### Example 1: Configuring Multiple Robots with RVO Behavior
 
 ```yaml
@@ -582,22 +590,19 @@ robot:
     plot:
       show_trajectory: True
 ```
-> [!NOTE]  
-> Highlights information that users should take into account, even when skimming.
-> 
-> [!NOTE]
-> When configuring multiple objects, use the `number` and `distribution` parameters to efficiently generate them. For instance, setting `number: 10` with a `distribution` of `'random'` can quickly populate the simulation with randomly placed objects. 
-> - **Dictionary Parameters**: All dictionary-type parameters (e.g., `distribution`, `shape`, `kinematics`, `behavior`) must include a `'name'` key to specify their type. Omitting the `'name'` key will result in default values or errors.
-> - **Group Configurations**: By default, objects within the same group share configurations. To customize individual objects within a group, add sub-parameters using `-`. Unspecified objects will inherit the last defined configuration within the group.
-> - **Kinematics and Velocities**: Ensure that the `velocity` and `vel_max` parameters match the kinematics model. For example, a differential drive robot (`'diff'`) should have velocities in `[v, omega]`, while an omnidirectional robot (`'omni'`) uses `[vx, vy]`.
-> - **Plotting Options**: Customize the visualization of your simulation through the `plot` parameter for each object if the `plot` section is located in the object configuration. If it is located in the root of the object configuration, it will be applied to all objects. 
 
-By carefully configuring these parameters, you can create a rich and dynamic simulation environment tailored to your specific needs.
+:::{Note}
+- **Multiple Objects**: When configuring multiple objects, use the `number` and `distribution` parameters to efficiently generate them. For instance, setting `number: 10` with a `distribution` of `'random'` can quickly populate the simulation with randomly placed objects. 
+- **Dictionary Parameters**: All dictionary-type parameters (e.g., `distribution`, `shape`, `kinematics`, `behavior`) must include a `'name'` key to specify their type. Omitting the `'name'` key will result in default values or errors.
+- **Group Configurations**: By default, objects within the same group share configurations. To customize individual objects within a group, add sub-parameters using `-`. Unspecified objects will inherit the last defined configuration within the group.
+- **Kinematics and Velocities**: Ensure that the `velocity` and `vel_max` parameters match the kinematics model. For example, a differential drive robot (`'diff'`) should have velocities in `[v, omega]`, while an omnidirectional robot (`'omni'`) uses `[vx, vy]`.
+- **Plotting Options**: Customize the visualization of your simulation through the `plot` parameter for each object if the `plot` section is located in the object configuration. If it is located in the root of the object configuration, it will be applied to all objects. 
+:::
 
+By carefully configuring these parameters, you can create a rich and dynamic simulation environment tailored to your specific needs.
 
 
 
 
-- **Multiple Objects**: 
 
 

doc/source/irsim.env.rst

@@ -9,6 +9,11 @@ irsim.env.env\_base
    :undoc-members:
    :show-inheritance:
 
+.. automodule:: irsim.env.env_base3d
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 irsim.env.env\_logger
 ------------------------------
 

doc/source/irsim.rst

@@ -0,0 +1,7 @@
+irsim
+===================
+
+.. automodule:: irsim
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/source/irsim.world.rst

@@ -2,14 +2,15 @@ world
 =====================
 
 
-irsim.world.object\_base 
----------------------------------
+irsim.world
+--------------------------
 
-.. automodule:: irsim.world.object_base
+.. automodule:: irsim.world.world
    :members:
    :undoc-members:
    :show-inheritance:
 
+
 irsim.world.object\_factory 
 ------------------------------------
 
@@ -18,16 +19,25 @@ irsim.world.object\_factory
    :undoc-members:
    :show-inheritance:
 
-irsim.world.world
---------------------------
-
-.. automodule:: irsim.world.world
+.. automodule:: irsim.world.object_base
    :members:
    :undoc-members:
    :show-inheritance:
 
 
-.. automodule:: irsim.world
+irsim.world.sensor\_factory 
+------------------------------------
+
+.. automodule:: irsim.world.sensors.sensor_factory
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: irsim.world.sensors.lidar2d
    :members:
    :undoc-members:
    :show-inheritance:
+
+
+
+

doc/source/modules.rst

@@ -4,6 +4,7 @@ irsim
 .. toctree::
    :maxdepth: 4
 
+   irsim
    irsim.env
    irsim.lib
    irsim.world

doc/source/usage/make_environment.md

@@ -11,7 +11,7 @@ import irsim
 env = irsim.make('empty_world.yaml')
 ```
 
-The `make` function creates an environment from a configuration file. Support parameters can be found in [EnvBase]() class. The configuration file is a YAML file that specifies the properties of the environment. The `empty_world.yaml` file is a simple configuration file that creates an empty environment. This file is listed below:
+The `make` function creates an environment from a configuration file. Support parameters can be found in [EnvBase](#irsim.env.env_base.EnvBase) class. The configuration file is a YAML file that specifies the properties of the environment. The `empty_world.yaml` file is a simple configuration file that creates an empty environment. This file is listed below:
 
 ```yaml
 world:
@@ -25,5 +25,4 @@ world:
   obstacle_map: null # the path of obstacle map
 ```
 
-The detailed YAML configuration syntax is introduced in the [YAML Syntax]()
 

irsim/__init__.py

@@ -6,6 +6,18 @@
 
 def make(world_name=None, projection=None, **kwargs) -> EnvBase:
 
+    '''
+    Create an environment by the given world file and projection.
+
+    Args:
+        world_name (str): The name of the world file. If not specified, the default name of the `python script` will be used.
+        projection (str): The projection of the environment. Default is "None". If set to "3d", the environment will be a 3D plot environment.
+        **kwargs: Additional keyword arguments for 
+            :py:class:`.EnvBase` or :py:class:`.EnvBase3D` for more details. 
+    Returns:
+        The environment object
+    '''
+
     world_name = world_name or os.path.basename(sys.argv[0]).split(".")[0] + ".yaml"
 
     if projection == "3d":

irsim/env/env_base.py

@@ -146,8 +146,8 @@ def render(self, interval=0.05, figure_kwargs=dict(), **kwargs):
 
         Args:
             interval(float) :  Time interval between frames in seconds.
-            figure_kwargs(dict) : Additional keyword arguments for saving figures,  see https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html for detail.
-            kwargs: Additional keyword arguments for drawing components. see object_base.plot() function for detail.
+            figure_kwargs(dict) : Additional keyword arguments for saving figures, see `savefig <https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html>`_ for detail.
+            kwargs: Additional keyword arguments for drawing components. see :py:meth:`.ObjectBase.plot` function for detail.
         """
 
         if not self.disable_all_plot:
@@ -177,7 +177,7 @@ def draw_trajectory(self, traj, traj_type="g-", **kwargs):
         Args:
             traj (list): List of trajectory points (2 * 1 vector).
             traj_type: Type of the trajectory line, see matplotlib plot function for detail.
-            **kwargs: Additional keyword arguments for drawing the trajectory, see env_plot.draw_trajectory() function for detail.
+            **kwargs: Additional keyword arguments for drawing the trajectory, see :py:meth:`.EnvPlot.draw_trajectory` for detail.
         """
 
         self._env_plot.draw_trajectory(traj, traj_type, **kwargs)
@@ -191,7 +191,7 @@ def draw_points(self, points, s=30, c="b", refresh=True, **kwargs):
             s (int): Size of the points.
             c (str): Color of the points.
             refresh (bool): Flag to refresh the points in the figure.
-            **kwargs: Additional keyword arguments for drawing the points, see ax.scatter (https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.scatter.html) function for detail.
+            **kwargs: Additional keyword arguments for drawing the points, see `ax.scatter <https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.scatter.html>`_ function for detail.
         """
 
         self._env_plot.draw_points(points, s, c, refresh, **kwargs)
@@ -284,7 +284,7 @@ def end(self, ending_time=3.0, **kwargs):
 
         Args:
             ending_time (float): Time in seconds to wait before closing the figure, default is 3 seconds.
-            **kwargs: Additional keyword arguments for saving the animation, see env_plot.save_animate() function for detail.
+            **kwargs: Additional keyword arguments for saving the animation, see :py:meth:`.EnvPlot.save_animate` for detail.
         """
 
         if self.disable_all_plot:
@@ -450,7 +450,7 @@ def get_lidar_scan(self, id=0):
             id (int): Id of the robot.
 
         Returns:
-            Dict: Dict of lidar scan points, see lidar2d/get_scan() for detail.
+            Dict: Dict of lidar scan points, see :py:meth:`.world.sensors.lidar2d.Lidar2D.get_scan` for detail.
         """
 
         return self.robot_list[id].get_lidar_scan()
@@ -474,7 +474,7 @@ def get_obstacle_list(self):
         Get the information of the obstacles in the environment.
 
         Returns:
-            list of dict: List of obstacle information, see Obstacle_Info in Object_base for detail.
+            list of dict: List of obstacle information, see :py:meth:`.ObjectBase.get_obstacle_info` for detail.
         """
 
         return [
@@ -489,7 +489,7 @@ def get_robot_info(self, id=0):
             id (int): Id of the robot.
 
         Returns:
-            see ObjectInfo in Object_base for detail
+            see :py:meth:`.ObjectBase.get_info` for detail
         """
 
         return self.robot_list[id].get_info()
@@ -503,7 +503,7 @@ def save_figure(
         Save the current figure.
         Args:
             save_name: Name of the file with format to save the figure.
-            **kwargs: Additional keyword arguments for saving the figure, see matplotlib.pyplot.savefig() function for detail.
+            **kwargs: Additional keyword arguments for saving the figure, see `savefig <https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html>`_ function for detail.
         """
         file_save_name = save_name or self._world.name + ".png"
 

irsim/env/env_base3d.py

@@ -8,6 +8,10 @@
 
 class EnvBase3D(EnvBase):
 
+    '''
+    This class is the 3D version of the environment class. It inherits from the :py:class:`.EnvBase` class to provide the 3D plot environment.
+    '''
+
     def __init__(self, world_name, **kwargs):
 
         super().__init__(world_name, **kwargs)

irsim/env/env_plot.py

@@ -174,7 +174,7 @@ def draw_trajectory(
             label (str): Label for the trajectory.
             show_direction (bool): Whether to show the direction of the trajectory.
             refresh (bool): Whether to refresh the plot.
-            kwargs: Additional plotting options.
+            kwargs: Additional plotting options for ax.plot()
         """
         if isinstance(traj, list):
             path_x_list = [p[0, 0] for p in traj]

irsim/world/object_base.py

@@ -609,12 +609,32 @@ def input_state_check(self, state, dim=3):
             return state
 
     def plot(self, ax, **kwargs):
+
         """
         Plot the object on a given axis.
 
         Args:
             ax: Matplotlib axis.
-            **kwargs: Additional plotting options.
+            kwargs:
+                - show_goal (bool): Whether show the goal position.  
+                - show_text (bool): Whether show text information. To be completed.  
+                - show_arrow (bool): Whether show the velocity arrow.
+                - show_uncertainty (bool): Whether show the uncertainty. To be completed.
+                - show_trajectory (bool): Whether show the trajectory.
+                - show_trail (bool): Whether show the trail.
+                - show_sensor (bool): Whether show the sensor.
+                - trail_freq (int): Frequency of trail display.
+                - goal_color (str): Color of the goal marker.
+                - traj_color (str): Color of the trajectory.
+                - traj_style (str): Style of the trajectory.
+                - traj_width (float): Width of the trajectory.
+                - traj_alpha (float): Transparency of the trajectory.
+                - edgecolor (str): Edge color of the trail.
+                - linewidth (float): Width of the trail.
+                - trail_alpha (float): Transparency of the trail.
+                - trail_fill (bool): Whether fill the trail.
+                - trail_color (str): Color of the trail.
+
         """
         self.state_re = self.state
         self.goal_re = self.goal
@@ -961,13 +981,12 @@ def get_obstacle_info(self):
         Get information about the object as an obstacle.
 
         Returns:
-            ObstacleInfo: Obstacle-related information.
+            ObstacleInfo: Obstacle-related information, including state, vertices, velocity, and radius.
         """
         return ObstacleInfo(
             self.state[:2, :],
             self.vertices[:, :-1],
             self._velocity,
-            self.info.cone_type,
             self.radius,
         )