Improve API reference detail and coverage#252
Conversation
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 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR expands and restructures the Sphinx API reference pages for EmbodiChain to provide clearer package overviews and more complete coverage of simulation and RL subpackages.
Changes:
- Enhanced the API reference index and added missing package pages (e.g.,
embodichain.data, RL collector). - Expanded
lab.simandlab.sim.utilitydocumentation with overviews and deeper submodule/member listings. - Improved RL package docs structure by adding overview text and dedicated pages for submodules.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/source/api_reference/index.rst | Improves top-level API reference intro and adds data to the core module listing. |
| docs/source/api_reference/embodichain/embodichain.utils.rst | Adds additional utils submodules to the documented submodule list. |
| docs/source/api_reference/embodichain/embodichain.lab.sim.utility.rst | Adds an overview and documents many utility submodules with automodule sections. |
| docs/source/api_reference/embodichain/embodichain.lab.sim.types.rst | Adds overview and explicit type-alias documentation via autosummary/autodata. |
| docs/source/api_reference/embodichain/embodichain.lab.sim.rst | Adds a package overview, expands submodule listing, and adds sections for robots/types/atomic actions. |
| docs/source/api_reference/embodichain/embodichain.lab.sim.robots.rst | Adds overview and class documentation for CobotMagicCfg. |
| docs/source/api_reference/embodichain/embodichain.data.rst | Introduces new API reference page for embodichain.data and its submodules. |
| docs/source/api_reference/embodichain/embodichain.agents.rst | Adds collector to the RL submodule listing. |
| docs/source/api_reference/embodichain/embodichain.agents.rl.utils.rst | Adds overview and expands submodule/member documentation for RL utils. |
| docs/source/api_reference/embodichain/embodichain.agents.rl.train.rst | Adds overview and attempts to expand function/member documentation. |
| docs/source/api_reference/embodichain/embodichain.agents.rl.rst | Adds overview and links/sections for collector APIs. |
| docs/source/api_reference/embodichain/embodichain.agents.rl.models.rst | Adds overview and attempts to expand function/member documentation. |
| docs/source/api_reference/embodichain/embodichain.agents.rl.collector.rst | New page documenting collector classes (BaseCollector, SyncCollector). |
| docs/source/api_reference/embodichain/embodichain.agents.rl.buffer.rst | Adds overview and expands buffer submodule documentation. |
| docs/source/api_reference/embodichain/embodichain.agents.rl.algo.rst | Adds overview and attempts to expand algorithm registry documentation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| .. automodule:: embodichain.agents.rl.algo | ||
|
|
||
| Overview | ||
| -------- | ||
|
|
||
| Algorithm registry and algorithm-construction helpers for RL training. | ||
|
|
||
|
|
||
| .. rubric:: Functions | ||
|
|
||
| .. autosummary:: | ||
|
|
||
| build_algo | ||
| get_registered_algo_names | ||
|
|
||
| .. automodule:: embodichain.agents.rl.algo | ||
| :members: | ||
| :undoc-members: |
There was a problem hiding this comment.
This page declares .. automodule:: embodichain.agents.rl.algo twice (once at the top and again with :members:). This typically duplicates rendered content and can produce Sphinx warnings. Keep only a single automodule directive (and add options to that one if needed).
|
|
||
| .. rubric:: Functions | ||
|
|
||
| .. autosummary:: | ||
|
|
||
| build_algo | ||
| get_registered_algo_names |
There was a problem hiding this comment.
The .. rubric:: Functions / .. autosummary:: block is indented even though it is not inside another directive’s content. In reStructuredText this indentation makes it a block quote, which can lead to odd formatting and/or docutils warnings. Unindent these directives to column 0 (or intentionally nest them under the automodule directive, but then the Overview section would need to be structured accordingly).
| @@ -13,4 +18,9 @@ | |||
| get_policy_class | |||
| get_registered_policy_names | |||
| register_policy | |||
|
|
|||
| .. automodule:: embodichain.agents.rl.models | |||
| :members: | |||
| :undoc-members: | |||
| :show-inheritance: | |||
There was a problem hiding this comment.
This page declares .. automodule:: embodichain.agents.rl.models twice (top and again with :members:). That usually duplicates output and can trigger Sphinx warnings. Prefer a single automodule directive with the desired options.
| @@ -13,4 +18,9 @@ | |||
| get_policy_class | |||
| get_registered_policy_names | |||
| register_policy | |||
There was a problem hiding this comment.
The .. rubric:: Functions / .. autosummary:: block is indented even though it isn't nested under another directive. This indentation makes it a block quote in RST, which can render strangely and/or cause docutils warnings. Unindent these directives to the left margin (or restructure so they are intentionally within an automodule content block).
| @@ -11,4 +16,9 @@ | |||
| main | |||
| parse_args | |||
| train_from_config | |||
|
|
|||
| .. automodule:: embodichain.agents.rl.train | |||
| :members: | |||
| :undoc-members: | |||
| :show-inheritance: | |||
There was a problem hiding this comment.
This page declares .. automodule:: embodichain.agents.rl.train twice (once at the top and again with :members:). This can duplicate rendered content and may raise Sphinx warnings. Keep a single automodule directive and attach the desired options to it.
| @@ -11,4 +16,9 @@ | |||
| main | |||
| parse_args | |||
| train_from_config | |||
There was a problem hiding this comment.
The .. rubric:: Functions / .. autosummary:: block is indented but not actually inside another directive’s content. In RST this becomes a block quote and can lead to incorrect rendering/warnings. Unindent these directives to column 0 (or explicitly nest them under an automodule directive and adjust surrounding structure).
Description
This PR improves the API reference documentation under .
It expands sparse module pages with clearer overviews, adds missing API references, and improves section structure/readability for RL and simulation modules.
Dependencies: None
Issue reference: N/A
Type of change
Screenshots
N/A
Checklist
Generated with Claude Code