Update docs for flattened dartpy namespace

Author: jslee02

docs/onboarding/README.md

@@ -558,13 +558,10 @@ graph TB
 
 **Key Modules**:
 
-- `dartpy.math` - Mathematical utilities and Eigen↔NumPy conversion
-- `dartpy.dynamics` - Skeletons, BodyNodes, Joints, IK
-- `dartpy.collision` - Collision detection backends
-- `dartpy.constraint` - Constraint solving
-- `dartpy.simulation` - World simulation
+- `dartpy` (top-level) - Core classes/functions (math, dynamics, collision, simulation, constraint, optimizer) exposed in snake_case
+- `dartpy.io` - File parsers (URDF, SDF, SKEL, MJCF) [alias for legacy `utils`]
 - `dartpy.gui` - 3D visualization with OSG and ImGui
-- `dartpy.utils` - File parsers (URDF, SDF, SKEL, MJCF)
+- Legacy `dartpy.common`/`math`/`dynamics`/`collision`/`simulation`/`constraint`/`optimizer`/`utils` remain importable in DART 7.x but emit `DeprecationWarning` and will be removed in DART 8.0.
 
 **Key Files**:
 
@@ -818,20 +815,20 @@ sequenceDiagram
     participant NumPy as NumPy
 
     Python->>dartpy: import dartpy
-    Python->>dartpy: world = dartpy.simulation.World()
+    Python->>dartpy: world = dartpy.World()
     dartpy->>DART: World::create()
 
     Python->>dartpy: skel = dartpy.dynamics.Skeleton.create()
     dartpy->>DART: Skeleton::create()
 
-    Python->>dartpy: world.addSkeleton(skel)
+    Python->>dartpy: world.add_skeleton(skel)
     dartpy->>DART: World::addSkeleton()
 
     loop Simulation
         Python->>dartpy: world.step()
         dartpy->>DART: World::step()
-        Python->>dartpy: q = skel.getPositions()
-        dartpy->>DART: Skeleton::getPositions()
+        Python->>dartpy: q = skel.get_positions()
+        dartpy->>DART: Skeleton::get_positions()
         DART->>NumPy: convert Eigen to ndarray
         NumPy-->>Python: positions array
     end
@@ -1207,7 +1204,7 @@ dart_gui/
 ```python
 import dartpy as dart
 from dartpy.gui import Viewer, RealTimeWorldNode
-from dartpy.utils import DartLoader
+from dartpy.io import DartLoader
 ```
 
 ---

docs/readthedocs/dartpy/python_api_reference.rst

@@ -22,14 +22,21 @@ To explore the bindings locally:
    pip install dartpy
    python - <<'PY'
    import dartpy as dart
-   world = dart.simulation.World()
-   print(world.getGravity())
+   world = dart.World()
+   print(world.get_gravity())
    PY
 
 Module Reference
 ----------------
 
-The sections below mirror the module layout from ``docs/python_api/``.
+.. note::
+   The dartpy API is now flattened: core classes/functions live on the
+   top-level ``dartpy`` package and file parsers under ``dartpy.io``. The
+   legacy submodules below remain importable in DART 7.x for compatibility but
+   are deprecated and scheduled for removal in DART 8.0. Prefer importing from
+   ``dartpy`` / ``dartpy.io`` in new code.
+
+The sections below mirror the legacy module layout from ``docs/python_api/`` (kept for compatibility):
 
 .. toctree::
    :maxdepth: 1