Add class-level docstrings to Python bindings (#3164)

* Add class-level docstrings to Python bindings

This commit adds docstrings to all Python binding classes in gz-sim.

Classes updated:
- Server, ServerConfig, TestFixture, UpdateInfo
- EntityComponentManager
- World, Model, Link, Joint
- Actor, Light, Sensor

Resolves #2968

Signed-off-by: anuragroy2001 <[email protected]>

* Update python/src/gz/sim/ServerConfig.cc

Co-authored-by: Ian Chen <[email protected]>
Signed-off-by: Arjo Chakravarty <[email protected]>

---------

Signed-off-by: anuragroy2001 <[email protected]>
Signed-off-by: Arjo Chakravarty <[email protected]>
Co-authored-by: Arjo Chakravarty <[email protected]>
Co-authored-by: Ian Chen <[email protected]>

Author: 3 people

python/src/gz/sim/Actor.cc

@@ -32,7 +32,10 @@ namespace python
 {
 void defineSimActor(py::object module)
 {
-  py::class_<gz::sim::Actor>(module, "Actor")
+  py::class_<gz::sim::Actor>(module, "Actor",
+    "A convenience wrapper around an actor entity. Actors are animated models "
+    "that can follow trajectories and play animations. This class provides easy "
+    "access to actor properties such as pose, trajectory, and animation state.")
   .def(py::init<gz::sim::Entity>())
   .def(py::init<gz::sim::Actor>())
   .def("entity", &gz::sim::Actor::Entity,

python/src/gz/sim/EntityComponentManager.cc

@@ -27,7 +27,9 @@ namespace python
 void defineSimEntityComponentManager(pybind11::object module)
 {
   pybind11::class_<gz::sim::EntityComponentManager>(
-      module, "EntityComponentManager")
+      module, "EntityComponentManager",
+    "The Entity Component Manager (ECM) manages entities and their components "
+    "in the simulation.")
   .def(pybind11::init<>());
 }
 }  // namespace python

python/src/gz/sim/Joint.cc

@@ -32,7 +32,10 @@ namespace python
 {
 void defineSimJoint(py::object module)
 {
-  py::class_<gz::sim::Joint>(module, "Joint")
+  py::class_<gz::sim::Joint>(module, "Joint",
+    "A convenience wrapper around a joint entity. This class provides easy "
+    "access to joint properties such as pose, axis, type, position, velocity, "
+    "and forces.")
   .def(py::init<gz::sim::Entity>())
   .def(py::init<gz::sim::Joint>())
   .def("entity", &gz::sim::Joint::Entity,

python/src/gz/sim/Light.cc

@@ -30,7 +30,10 @@ namespace python
 {
 void defineSimLight(py::object module)
 {
-  py::class_<gz::sim::Light>(module, "Light")
+  py::class_<gz::sim::Light>(module, "Light",
+    "A convenience wrapper around a light entity. This class provides easy "
+    "access to light properties such as type, color, intensity, direction, "
+    "and attenuation.")
   .def(py::init<gz::sim::Entity>())
   .def(py::init<gz::sim::Light>())
   .def("entity", &gz::sim::Light::Entity,

python/src/gz/sim/Link.cc

@@ -29,7 +29,10 @@ namespace python
 {
 void defineSimLink(py::object module)
 {
-  py::class_<gz::sim::Link>(module, "Link")
+   py::class_<gz::sim::Link>(module, "Link",
+    "A convenience wrapper around a link entity. This class provides easy "
+    "access to link properties such as pose, velocity, acceleration, forces, "
+    "and child entities (collisions, sensors, visuals).")
   .def(py::init<gz::sim::Entity>())
   .def(py::init<gz::sim::Link>())
   .def("entity", &gz::sim::Link::Entity,

python/src/gz/sim/Model.cc

@@ -30,7 +30,10 @@ namespace python
 {
 void defineSimModel(py::object module)
 {
-  py::class_<gz::sim::Model>(module, "Model")
+  py::class_<gz::sim::Model>(module, "Model",
+  "A convenience wrapper around a model entity. This class provides easy "
+  "access to model properties (static, self-collide, wind mode) and child "
+  "entities (joints, links).")
   .def(py::init<gz::sim::Entity>())
   .def(py::init<gz::sim::Model>())
   .def("entity", &gz::sim::Model::Entity,

python/src/gz/sim/Sensor.cc

@@ -30,7 +30,9 @@ namespace python
 {
 void defineSimSensor(py::object module)
 {
-  py::class_<gz::sim::Sensor>(module, "Sensor")
+  py::class_<gz::sim::Sensor>(module, "Sensor",
+    "A convenience wrapper around a sensor entity. This class provides easy "
+    "access to sensor properties such as pose, topic, and parent entity.")
   .def(py::init<gz::sim::Entity>())
   .def(py::init<gz::sim::Sensor>())
   .def("entity", &gz::sim::Sensor::Entity,

python/src/gz/sim/Server.cc

@@ -31,7 +31,10 @@ namespace python
 void defineSimServer(pybind11::object module)
 {
   pybind11::class_<gz::sim::Server,
-    std::shared_ptr<gz::sim::Server>>(module, "Server")
+    std::shared_ptr<gz::sim::Server>>(module, "Server",
+    "The main simuulation server class. This class manages the simulation "
+    "execution and provides control over running, pausing, and stepping "
+    "through simulations.")
   .def(pybind11::init<gz::sim::ServerConfig &>())
   .def(
     "run", &gz::sim::Server::Run,

python/src/gz/sim/ServerConfig.cc

@@ -29,7 +29,9 @@ namespace python
 {
 void defineSimServerConfig(pybind11::object module)
 {
-  pybind11::class_<gz::sim::ServerConfig>(module, "ServerConfig")
+  pybind11::class_<gz::sim::ServerConfig>(module, "ServerConfig",
+    "Configuration for a simulation server. This class provides options "
+    "for setting up and initializing a server, such as specifying the SDF file to use. ")
   .def(pybind11::init<>())
   .def(
     "set_sdf_file", &gz::sim::ServerConfig::SetSdfFile,

python/src/gz/sim/TestFixture.cc

@@ -32,7 +32,10 @@ namespace python
 void
 defineSimTestFixture(pybind11::object module)
 {
-  pybind11::class_<TestFixture, std::shared_ptr<TestFixture>> testFixture(module, "TestFixture");
+  pybind11::class_<TestFixture, std::shared_ptr<TestFixture>> testFixture(module, "TestFixture",
+    "A test fixture for setting up simulation tests. This class allows you to "
+    "configure callbacks (pre-update, update, post-update, reset) and interact "
+    "with a simulation server for testing purposes. ");
 
   // Since this class starts with "Test", pytest thinks it's a test and emits a
   // warning when it can't "collect" it.