Docs(gym): add hyperlinks and JSON config examples to functor docs by yuecideng · Pull Request #220 · DexForce/EmbodiChain

yuecideng · 2026-04-06T08:58:56Z

Description

This PR enhances all five functor documentation pages in docs/source/overview/gym/ with two improvements:

Sphinx cross-reference hyperlinks — Every functor and action term name now links to its source using {func} or {class} roles (e.g., {func}\~randomization.physics.randomize_rigid_object_mass``), so users can click through to the implementation.
Embedded JSON config examples — Each functor entry now includes a representative JSON configuration snippet (derived from the configs/gym/pour_water/gym_config_simple.json example) placed directly in the description column, giving users ready-to-copy config snippets.

Files changed

File	Functors covered
`event_functors.md`	25 event functors (physics, visual, spatial, geometry, asset management)
`observation_functors.md`	14 observation functors (pose, sensor, keypoints, normalization, properties, target)
`reward_functors.md`	9 reward functors (distance, alignment, task-specific, penalty)
`action_functors.md`	7 action terms (joint position, end-effector, velocity, force)
`dataset_functors.md`	1 dataset functor (LeRobotRecorder)

Type of change

Bug fix (non-breaking change which fixes an issue)
Enhancement (non-breaking change which improves an existing functionality)
New feature (non-breaking change which adds functionality)
Breaking change (existing functionality will not work without user modification)
Documentation update

Screenshots

N/A (text-based documentation changes)

Checklist

I have run the black . command to format the code base.
I have made corresponding changes to the documentation
I have added tests that prove my fix is effective or that my feature works
Dependencies have been updated, if applicable.

🤖 Generated with Claude Code

Add Sphinx cross-reference hyperlinks ({func}/{class}) for every functor and action term across all five functor documentation pages. Embed representative JSON configuration snippets (derived from the pour_water example config) inside each table's description column, giving users ready-to-copy config examples alongside each functor description. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Documentation update to improve the Gym functor reference pages by adding Sphinx cross-reference hyperlinks to implementations and embedding representative JSON configuration snippets for each functor/term.

Changes:

Added {func} / {class} cross-references for functors and action terms so readers can click through to source implementations.
Embedded JSON configuration examples inline in the list-table descriptions across the functor docs.
Adjusted list-table column widths to accommodate the embedded examples.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
docs/source/overview/gym/event_functors.md	Adds cross-references and JSON examples for event/randomization functors (several examples need to be aligned with actual signatures).
docs/source/overview/gym/observation_functors.md	Adds cross-references and JSON examples for observation functors (several examples don’t match required parameters/shape).
docs/source/overview/gym/reward_functors.md	Adds cross-references and JSON examples for reward functors (multiple examples use incorrect parameter names/keys).
docs/source/overview/gym/action_functors.md	Adds cross-references and JSON snippets for action terms.
docs/source/overview/gym/dataset_functors.md	Adds cross-references and a JSON snippet for the dataset recorder functor.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-06T09:07:21Z

+
+    ```json
+    {"func": "distance_to_target", "weight": 1.0,
+     "params": {"entity_cfg": {"uid": "bottle"},


The JSON example for distance_to_target uses entity_cfg, but the reward functor signature expects source_entity_cfg (see embodichain/lab/gym/envs/managers/rewards.py). Update the example params key so it matches the actual config schema.

Suggested change

"params": {"entity_cfg": {"uid": "bottle"},

"params": {"source_entity_cfg": {"uid": "bottle"},

Copilot · 2026-04-06T09:07:21Z

+     "params": {"robot_uid": "CobotMagic", "part_name": "left_arm",
+                "object_cfg": {"uid": "bottle"},
+                "target_cfg": {"uid": "cup"}}}


The reaching_behind_object JSON snippet lists params (robot_uid, target_cfg) that the functor does not accept; the implementation takes object_cfg, target_pose_key, behind_offset, height_offset, distance_scale, and part_name. Please update the example to only include supported parameters.

Suggested change

"params": {"robot_uid": "CobotMagic", "part_name": "left_arm",

"object_cfg": {"uid": "bottle"},

"target_cfg": {"uid": "cup"}}}

"params": {"part_name": "left_arm",

"object_cfg": {"uid": "bottle"},

"target_pose_key": "goal_pose",

"behind_offset": 0.1, "height_offset": 0.0,

"distance_scale": 10.0}}

Copilot · 2026-04-06T09:07:21Z

+
+    ```json
+    {"func": "joint_limit_penalty", "weight": 0.01,
+     "params": {"robot_uid": "CobotMagic", "part_name": "left_arm",


joint_limit_penalty does not accept part_name; it expects joint_ids (or uses the default slice) plus margin and robot_uid. The JSON example should be adjusted to use supported keys (or omit joint_ids if relying on defaults).

Suggested change

"params": {"robot_uid": "CobotMagic", "part_name": "left_arm",

"params": {"robot_uid": "CobotMagic",

Copilot · 2026-04-06T09:07:21Z

+    {"func": "get_sensor_pose_in_robot_frame", "mode": "add",
+     "name": "sensor/cam/pose_in_robot",
+     "params": {"entity_cfg": {"uid": "cam_high"},
+                "robot_cfg": {"uid": "CobotMagic"}}}


get_sensor_pose_in_robot_frame takes robot_uid (string) rather than a nested robot_cfg object. The JSON example as written won’t match the functor signature in observations.py and will fail to resolve the robot.

Suggested change

"robot_cfg": {"uid": "CobotMagic"}}}

"robot_uid": "CobotMagic"}}

Copilot · 2026-04-06T09:07:22Z

+    ```json
+    {"func": "compute_semantic_mask", "mode": "add",
+     "name": "sensor/cam/semantic_mask",
+     "params": {"entity_cfg": {"uid": "cam_high"}}}


compute_semantic_mask requires a foreground_uids parameter (no default). The JSON snippet omits it, so the example config would be invalid; add a representative foreground_uids list (and optionally is_right).

Suggested change

"params": {"entity_cfg": {"uid": "cam_high"}}}

"params": {"entity_cfg": {"uid": "cam_high"},

"foreground_uids": ["bottle", "cup"]}}

Copilot · 2026-04-06T09:07:23Z

+     "params": {"entity_cfg": {"uid": "cup"}, "base_color": [0.8, 0.2, 0.2]}}
+    ```
+* - {func}`~randomization.visual.set_rigid_object_group_visual_material`
  - Set a rigid object group's visual material deterministically (non-random). Useful for configs that want fixed colors/materials during reset.
+
+    ```json
+    {"func": "set_rigid_object_group_visual_material", "mode": "reset",
+     "params": {"entity_cfg": {"uid": "objects"}, "base_color": [0.8, 0.2, 0.2]}}


set_rigid_object_visual_material expects a mat_cfg dict (converted to VisualMaterialCfg), not a top-level base_color param. Also base_color is RGBA in VisualMaterialCfg (length 4). Update the JSON example accordingly.

Suggested change

"params": {"entity_cfg": {"uid": "cup"}, "base_color": [0.8, 0.2, 0.2]}}

```

* - {func}`~randomization.visual.set_rigid_object_group_visual_material`

- Set a rigid object group's visual material deterministically (non-random). Useful for configs that want fixed colors/materials during reset.

```json

{"func": "set_rigid_object_group_visual_material", "mode": "reset",

"params": {"entity_cfg": {"uid": "objects"}, "base_color": [0.8, 0.2, 0.2]}}

"params": {"entity_cfg": {"uid": "cup"},

"mat_cfg": {"base_color": [0.8, 0.2, 0.2, 1.0]}}}

```

* - {func}`~randomization.visual.set_rigid_object_group_visual_material`

- Set a rigid object group's visual material deterministically (non-random). Useful for configs that want fixed colors/materials during reset.

```json

{"func": "set_rigid_object_group_visual_material", "mode": "reset",

"params": {"entity_cfg": {"uid": "objects"},

"mat_cfg": {"base_color": [0.8, 0.2, 0.2, 1.0]}}}

Copilot · 2026-04-06T09:07:23Z

+
+    ```json
+    {"func": "set_rigid_object_group_visual_material", "mode": "reset",
+     "params": {"entity_cfg": {"uid": "objects"}, "base_color": [0.8, 0.2, 0.2]}}


set_rigid_object_group_visual_material expects mat_cfg (VisualMaterialCfg) rather than a top-level base_color, and base_color is RGBA (4 values). The JSON example should be updated to match the actual API.

Suggested change

"params": {"entity_cfg": {"uid": "objects"}, "base_color": [0.8, 0.2, 0.2]}}

"params": {"entity_cfg": {"uid": "objects"},

"mat_cfg": {"base_color": [0.8, 0.2, 0.2, 1.0]}}}

Copilot · 2026-04-06T09:07:23Z

+    ```json
+    {"func": "randomize_robot_qpos", "mode": "reset",
+     "params": {"entity_cfg": {"uid": "CobotMagic"},
+                "qpos_range": [[-0.1], [0.1]], "relative": true}}


randomize_robot_qpos uses the kwarg relative_qpos (not relative). As written, this JSON snippet won’t match the functor signature in randomization/spatial.py; rename the key to relative_qpos.

Suggested change

"qpos_range": [[-0.1], [0.1]], "relative": true}}

"qpos_range": [[-0.1], [0.1]], "relative_qpos": true}}

Copilot · 2026-04-06T09:07:23Z

+
+    ```json
+    {"func": "replace_assets_from_group", "mode": "reset",
+     "params": {"entity_cfg": {"uid": "cup"}, "group_uid": "cups_group"}}


The replace_assets_from_group functor requires folder_path (and entity_cfg) in its params; there is no group_uid parameter in the implementation. Please update the JSON example to use folder_path pointing to the asset group directory/pattern.

Suggested change

"params": {"entity_cfg": {"uid": "cup"}, "group_uid": "cups_group"}}

"params": {"entity_cfg": {"uid": "cup"}, "folder_path": "assets/cups/*"}}

Copilot · 2026-04-06T09:07:23Z

+                "pose_register_params": {"compute_relative": false,
+                                         "to_matrix": true}}}


register_entity_pose is called with kwargs like compute_relative, compute_pose_object_to_arena, and to_matrix; it does not accept a nested pose_register_params dict. This JSON example appears to use the register_info_to_env registry schema—please adjust it to pass supported parameters directly for register_entity_pose.

Suggested change

"pose_register_params": {"compute_relative": false,

"to_matrix": true}}}

"compute_relative": false,

"to_matrix": true}}

) Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings April 6, 2026 08:58

Copilot started reviewing on behalf of yuecideng April 6, 2026 08:59 View session

yuecideng added the docs Improvements or additions to documentation label Apr 6, 2026

Copilot AI reviewed Apr 6, 2026

View reviewed changes

yuecideng merged commit 9715c47 into main Apr 6, 2026
9 checks passed

yuecideng deleted the docs/functor-hyperlinks-and-json-examples branch April 6, 2026 09:13

yuecideng added a commit that referenced this pull request Apr 10, 2026

Docs(gym): add hyperlinks and JSON config examples to functor docs (#220

7d15274

) Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

chase6305 pushed a commit that referenced this pull request Apr 16, 2026

Docs(gym): add hyperlinks and JSON config examples to functor docs (#220

d5c31ac

) Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs(gym): add hyperlinks and JSON config examples to functor docs#220

Docs(gym): add hyperlinks and JSON config examples to functor docs#220
yuecideng merged 1 commit intomainfrom
docs/functor-hyperlinks-and-json-examples

yuecideng commented Apr 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Copilot AI Apr 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	"params": {"entity_cfg": {"uid": "bottle"},
	"params": {"source_entity_cfg": {"uid": "bottle"},

	"params": {"robot_uid": "CobotMagic", "part_name": "left_arm",
	"params": {"robot_uid": "CobotMagic",

	"robot_cfg": {"uid": "CobotMagic"}}}
	"robot_uid": "CobotMagic"}}

	"params": {"entity_cfg": {"uid": "cam_high"}}}
	"params": {"entity_cfg": {"uid": "cam_high"},
	"foreground_uids": ["bottle", "cup"]}}

	"params": {"entity_cfg": {"uid": "objects"}, "base_color": [0.8, 0.2, 0.2]}}
	"params": {"entity_cfg": {"uid": "objects"},
	"mat_cfg": {"base_color": [0.8, 0.2, 0.2, 1.0]}}}

	"qpos_range": [[-0.1], [0.1]], "relative": true}}
	"qpos_range": [[-0.1], [0.1]], "relative_qpos": true}}

	"params": {"entity_cfg": {"uid": "cup"}, "group_uid": "cups_group"}}
	"params": {"entity_cfg": {"uid": "cup"}, "folder_path": "assets/cups/*"}}

		"pose_register_params": {"compute_relative": false,
		"to_matrix": true}}}

Conversation

yuecideng commented Apr 6, 2026

Description

Files changed

Type of change

Screenshots

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants