From 883957c3a9a7de19ce6212e7dc94b6bd3f45da91 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Thu, 30 Apr 2026 18:07:17 +0000 Subject: [PATCH] docs(api): improve API reference coverage and structure Expand API reference docs with clearer module overviews, improved section\norganization, and additional autodoc coverage for sparse pages.\n\nAdd missing reference pages for data and RL collector modules, and\nwire them into the API index and package-level docs.\n\nImprove readability by fixing headings, directive structure, and\nsubmodule listings across simulation and utility pages.\n\nCo-Authored-By: Claude Opus 4.6 --- .../embodichain.agents.rl.algo.rst | 10 +++ .../embodichain.agents.rl.buffer.rst | 31 ++++++++ .../embodichain.agents.rl.collector.rst | 33 +++++++++ .../embodichain.agents.rl.models.rst | 10 +++ .../embodichain/embodichain.agents.rl.rst | 15 ++++ .../embodichain.agents.rl.train.rst | 10 +++ .../embodichain.agents.rl.utils.rst | 38 ++++++++++ .../embodichain/embodichain.agents.rst | 1 + .../embodichain/embodichain.data.rst | 51 +++++++++++++ .../embodichain.lab.sim.robots.rst | 19 +++++ .../embodichain/embodichain.lab.sim.rst | 74 +++++++++++++------ .../embodichain/embodichain.lab.sim.types.rst | 23 ++++++ .../embodichain.lab.sim.utility.rst | 72 +++++++++++++++++- .../embodichain/embodichain.utils.rst | 5 +- docs/source/api_reference/index.rst | 12 ++- 15 files changed, 377 insertions(+), 27 deletions(-) create mode 100644 docs/source/api_reference/embodichain/embodichain.agents.rl.collector.rst create mode 100644 docs/source/api_reference/embodichain/embodichain.data.rst diff --git a/docs/source/api_reference/embodichain/embodichain.agents.rl.algo.rst b/docs/source/api_reference/embodichain/embodichain.agents.rl.algo.rst index d5a1be05..35b11ab4 100644 --- a/docs/source/api_reference/embodichain/embodichain.agents.rl.algo.rst +++ b/docs/source/api_reference/embodichain/embodichain.agents.rl.algo.rst @@ -3,6 +3,11 @@ .. automodule:: embodichain.agents.rl.algo +Overview +-------- + +Algorithm registry and algorithm-construction helpers for RL training. + .. rubric:: Functions @@ -10,4 +15,9 @@ build_algo get_registered_algo_names + +.. automodule:: embodichain.agents.rl.algo + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/api_reference/embodichain/embodichain.agents.rl.buffer.rst b/docs/source/api_reference/embodichain/embodichain.agents.rl.buffer.rst index 0a178379..a79f3706 100644 --- a/docs/source/api_reference/embodichain/embodichain.agents.rl.buffer.rst +++ b/docs/source/api_reference/embodichain/embodichain.agents.rl.buffer.rst @@ -3,4 +3,35 @@ .. automodule:: embodichain.agents.rl.buffer +Overview +-------- + +The ``buffer`` package provides rollout and replay buffer structures used by +RL algorithms. + +.. rubric:: Submodules + +.. autosummary:: + + standard_buffer + utils + +.. currentmodule:: embodichain.agents.rl.buffer + +Rollout Buffer Classes +---------------------- + +.. automodule:: embodichain.agents.rl.buffer.standard_buffer + :members: + :undoc-members: + :show-inheritance: + +Buffer Utilities +---------------- + +.. automodule:: embodichain.agents.rl.buffer.utils + :members: + :undoc-members: + :show-inheritance: + \ No newline at end of file diff --git a/docs/source/api_reference/embodichain/embodichain.agents.rl.collector.rst b/docs/source/api_reference/embodichain/embodichain.agents.rl.collector.rst new file mode 100644 index 00000000..4fd639ed --- /dev/null +++ b/docs/source/api_reference/embodichain/embodichain.agents.rl.collector.rst @@ -0,0 +1,33 @@ +embodichain.agents.rl.collector +================================ + +.. automodule:: embodichain.agents.rl.collector + +Overview +-------- + +Collectors are responsible for interacting with vectorized environments and +assembling rollout data into a preallocated ``TensorDict`` layout. + +.. rubric:: Classes + +.. autosummary:: + + BaseCollector + SyncCollector + +.. currentmodule:: embodichain.agents.rl.collector + +BaseCollector +------------- + +.. autoclass:: BaseCollector + :members: + :show-inheritance: + +SyncCollector +------------- + +.. autoclass:: SyncCollector + :members: + :show-inheritance: diff --git a/docs/source/api_reference/embodichain/embodichain.agents.rl.models.rst b/docs/source/api_reference/embodichain/embodichain.agents.rl.models.rst index d74efb22..6de1449a 100644 --- a/docs/source/api_reference/embodichain/embodichain.agents.rl.models.rst +++ b/docs/source/api_reference/embodichain/embodichain.agents.rl.models.rst @@ -3,6 +3,11 @@ .. automodule:: embodichain.agents.rl.models +Overview +-------- + +Policy-network registration and model construction APIs for RL agents. + .. rubric:: Functions @@ -13,4 +18,9 @@ get_policy_class get_registered_policy_names register_policy + +.. automodule:: embodichain.agents.rl.models + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/api_reference/embodichain/embodichain.agents.rl.rst b/docs/source/api_reference/embodichain/embodichain.agents.rl.rst index 2fa64a6e..7dda1a38 100644 --- a/docs/source/api_reference/embodichain/embodichain.agents.rl.rst +++ b/docs/source/api_reference/embodichain/embodichain.agents.rl.rst @@ -3,6 +3,12 @@ embodichain.agents.rl .. automodule:: embodichain.agents.rl +Overview +-------- + +The ``embodichain.agents.rl`` package contains algorithm registries, rollout +collection logic, policy/model builders, and training entry points. + .. rubric:: Submodules .. autosummary:: @@ -10,6 +16,7 @@ embodichain.agents.rl algo buffer + collector models train utils @@ -30,6 +37,14 @@ Rollout Buffer :undoc-members: :show-inheritance: +Collectors +---------- + +.. automodule:: embodichain.agents.rl.collector + :members: + :undoc-members: + :show-inheritance: + Policy Models ------------- diff --git a/docs/source/api_reference/embodichain/embodichain.agents.rl.train.rst b/docs/source/api_reference/embodichain/embodichain.agents.rl.train.rst index 4376c750..7fb189eb 100644 --- a/docs/source/api_reference/embodichain/embodichain.agents.rl.train.rst +++ b/docs/source/api_reference/embodichain/embodichain.agents.rl.train.rst @@ -3,6 +3,11 @@ .. automodule:: embodichain.agents.rl.train +Overview +-------- + +Training entry points and command-line helpers for launching RL experiments. + .. rubric:: Functions @@ -11,4 +16,9 @@ main parse_args train_from_config + +.. automodule:: embodichain.agents.rl.train + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/api_reference/embodichain/embodichain.agents.rl.utils.rst b/docs/source/api_reference/embodichain/embodichain.agents.rl.utils.rst index 1f2706a5..b00828a3 100644 --- a/docs/source/api_reference/embodichain/embodichain.agents.rl.utils.rst +++ b/docs/source/api_reference/embodichain/embodichain.agents.rl.utils.rst @@ -3,4 +3,42 @@ .. automodule:: embodichain.agents.rl.utils +Overview +-------- + +The ``utils`` package contains helper utilities for RL configuration, +data conversion, and training orchestration. + +.. rubric:: Submodules + +.. autosummary:: + + config + helper + trainer + +Configuration Helpers +--------------------- + +.. automodule:: embodichain.agents.rl.utils.config + :members: + :undoc-members: + :show-inheritance: + +General Helpers +--------------- + +.. automodule:: embodichain.agents.rl.utils.helper + :members: + :undoc-members: + :show-inheritance: + +Trainer Utilities +----------------- + +.. automodule:: embodichain.agents.rl.utils.trainer + :members: + :undoc-members: + :show-inheritance: + \ No newline at end of file diff --git a/docs/source/api_reference/embodichain/embodichain.agents.rst b/docs/source/api_reference/embodichain/embodichain.agents.rst index b5942c7e..6b1e5589 100644 --- a/docs/source/api_reference/embodichain/embodichain.agents.rst +++ b/docs/source/api_reference/embodichain/embodichain.agents.rst @@ -48,6 +48,7 @@ Reinforcement Learning algo buffer + collector models train utils diff --git a/docs/source/api_reference/embodichain/embodichain.data.rst b/docs/source/api_reference/embodichain/embodichain.data.rst new file mode 100644 index 00000000..9d8b0984 --- /dev/null +++ b/docs/source/api_reference/embodichain/embodichain.data.rst @@ -0,0 +1,51 @@ +embodichain.data +================ + +.. automodule:: embodichain.data + +Data Package Overview +--------------------- + +The ``embodichain.data`` package centralizes dataset resolution and asset download +helpers used by simulation tasks and training pipelines. + +.. rubric:: Submodules + +.. autosummary:: + + constants + dataset + download + enum + +Constants +--------- + +.. automodule:: embodichain.data.constants + :members: + :undoc-members: + :show-inheritance: + +Dataset Resolution +------------------ + +.. automodule:: embodichain.data.dataset + :members: + :undoc-members: + :show-inheritance: + +Asset Download CLI +------------------ + +.. automodule:: embodichain.data.download + :members: + :undoc-members: + :show-inheritance: + +Enums +----- + +.. automodule:: embodichain.data.enum + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api_reference/embodichain/embodichain.lab.sim.robots.rst b/docs/source/api_reference/embodichain/embodichain.lab.sim.robots.rst index d6428af3..c3457108 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.sim.robots.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.sim.robots.rst @@ -3,4 +3,23 @@ .. automodule:: embodichain.lab.sim.robots +Overview +-------- + +This module exposes robot-specific configuration presets for simulation scenes. + +.. rubric:: Classes + +.. autosummary:: + + CobotMagicCfg + +.. currentmodule:: embodichain.lab.sim.robots + +.. autoclass:: CobotMagicCfg + :members: + :inherited-members: + :show-inheritance: + :exclude-members: __init__, copy, replace, to_dict, validate + \ No newline at end of file diff --git a/docs/source/api_reference/embodichain/embodichain.lab.sim.rst b/docs/source/api_reference/embodichain/embodichain.lab.sim.rst index 2a21fcf0..9977639d 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.sim.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.sim.rst @@ -3,21 +3,29 @@ .. automodule:: embodichain.lab.sim - .. rubric:: Submodules - - .. autosummary:: - :toctree: . - - sim_manager - cfg - common - material - shapes - objects - sensors - planners - solvers - utility +Overview +-------- + +The ``sim`` package provides simulation-core APIs including scene/object +management, materials, sensors, planning/IK utilities, and action helpers. + +.. rubric:: Submodules + +.. autosummary:: + :toctree: . + + sim_manager + cfg + common + material + shapes + objects + robots + sensors + planners + solvers + types + utility .. currentmodule:: embodichain.lab.sim @@ -35,8 +43,8 @@ Simulation Manager :show-inheritance: :exclude-members: __init__, copy, replace, to_dict, validate -Configurations ------------------- +Configuration +------------- .. automodule:: embodichain.lab.sim.cfg :members: @@ -44,8 +52,8 @@ Configurations :show-inheritance: :exclude-members: __init__, copy, replace, to_dict, validate -Common Conponents ------------------- +Common Components +----------------- .. automodule:: embodichain.lab.sim.common :members: @@ -53,7 +61,7 @@ Common Conponents :show-inheritance: Materials ------------------- +--------- .. automodule:: embodichain.lab.sim.material :members: @@ -61,7 +69,7 @@ Materials :show-inheritance: Shapes ------------------- +------ .. automodule:: embodichain.lab.sim.shapes :members: @@ -69,6 +77,14 @@ Shapes :show-inheritance: :exclude-members: __init__, copy, replace, to_dict, validate +Atomic Actions +-------------- + +.. automodule:: embodichain.lab.sim.atom_actions + :members: + :undoc-members: + :show-inheritance: + Objects ------- @@ -85,6 +101,14 @@ Sensors embodichain.lab.sim.sensors +Robot Configurations +-------------------- + +.. automodule:: embodichain.lab.sim.robots + :members: + :undoc-members: + :show-inheritance: + Solvers ------- @@ -101,6 +125,14 @@ Planners embodichain.lab.sim.planners +Shared Types +------------ + +.. automodule:: embodichain.lab.sim.types + :members: + :undoc-members: + :show-inheritance: + Utility ------- diff --git a/docs/source/api_reference/embodichain/embodichain.lab.sim.types.rst b/docs/source/api_reference/embodichain/embodichain.lab.sim.types.rst index 5b1c4bd8..f01bae1f 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.sim.types.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.sim.types.rst @@ -3,4 +3,27 @@ .. automodule:: embodichain.lab.sim.types +Overview +-------- + +Shared tensor/type aliases used across simulation, environment, and policy +interfaces. + +.. rubric:: Type Aliases + +.. autosummary:: + + Array + Device + EnvObs + EnvAction + +.. autodata:: Array + +.. autodata:: Device + +.. autodata:: EnvObs + +.. autodata:: EnvAction + \ No newline at end of file diff --git a/docs/source/api_reference/embodichain/embodichain.lab.sim.utility.rst b/docs/source/api_reference/embodichain/embodichain.lab.sim.utility.rst index f64d3ce3..2e45ea5d 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.sim.utility.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.sim.utility.rst @@ -3,21 +3,73 @@ embodichain.lab.sim.utility .. automodule:: embodichain.lab.sim.utility -Utility Functions ------------------ +Overview +-------- -This module contains utility functions for simulation, mesh processing, and URDF handling. +This package contains helper utilities for simulation state conversion, +mesh/geometry handling, configuration transforms, keyboard interaction, and +action/solver adaptation. .. rubric:: Submodules .. autosummary:: + action_utils + atom_action_utils + cfg_utils + gizmo_utils + import_utils + io_utils + keyboard_utils sim_utils mesh_utils - urdf_utils + solver_utils + tensor .. currentmodule:: embodichain.lab.sim.utility +Action Utilities +~~~~~~~~~~~~~~~~ + +.. automodule:: embodichain.lab.sim.utility.action_utils + :members: + +Atomic Action Utilities +~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: embodichain.lab.sim.utility.atom_action_utils + :members: + +Configuration Utilities +~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: embodichain.lab.sim.utility.cfg_utils + :members: + +Gizmo Utilities +~~~~~~~~~~~~~~~ + +.. automodule:: embodichain.lab.sim.utility.gizmo_utils + :members: + +Import Utilities +~~~~~~~~~~~~~~~~ + +.. automodule:: embodichain.lab.sim.utility.import_utils + :members: + +I/O Utilities +~~~~~~~~~~~~~ + +.. automodule:: embodichain.lab.sim.utility.io_utils + :members: + +Keyboard Utilities +~~~~~~~~~~~~~~~~~~ + +.. automodule:: embodichain.lab.sim.utility.keyboard_utils + :members: + Simulation Utils ~~~~~~~~~~~~~~~~ @@ -29,3 +81,15 @@ Mesh Utils .. automodule:: embodichain.lab.sim.utility.mesh_utils :members: + +Solver Utilities +~~~~~~~~~~~~~~~~ + +.. automodule:: embodichain.lab.sim.utility.solver_utils + :members: + +Tensor Utilities +~~~~~~~~~~~~~~~~ + +.. automodule:: embodichain.lab.sim.utility.tensor + :members: diff --git a/docs/source/api_reference/embodichain/embodichain.utils.rst b/docs/source/api_reference/embodichain/embodichain.utils.rst index 490962ce..c4d131a1 100644 --- a/docs/source/api_reference/embodichain/embodichain.utils.rst +++ b/docs/source/api_reference/embodichain/embodichain.utils.rst @@ -3,13 +3,16 @@ .. automodule:: embodichain.utils - .. Rubric:: Submodules + .. rubric:: Submodules .. autosummary:: warp + cfg configclass + device_utils file + img_utils logger math module_utils diff --git a/docs/source/api_reference/index.rst b/docs/source/api_reference/index.rst index fa3112ae..f73a7480 100644 --- a/docs/source/api_reference/index.rst +++ b/docs/source/api_reference/index.rst @@ -1,7 +1,16 @@ API Reference ============= -This page provides detailed documentation for all EmbodiChain modules and classes. +This section provides the API-level documentation for EmbodiChain's public Python +modules. + +Use this reference when you need: + +* module-level overviews and responsibilities, +* public classes, functions, and configuration objects, +* links into specialized subpackages (simulation, gym environments, RL, and utilities). + +The pages are organized from high-level package namespaces to concrete submodules. Core Framework -------------- @@ -14,6 +23,7 @@ The following modules are available in the core ``embodichain`` framework: :toctree: embodichain agents + data lab toolkits utils