Add public API documentation coverage workflow

[yuecideng]

Description

This PR adds a read-only public API documentation coverage workflow based on static __all__ declarations.

It introduces:

• docs/scripts/check_api_docs.py for dependency-free structural coverage checks with text and JSON reports
• module-scope control-flow discovery so branch-scoped static exports cannot bypass coverage checks
• an agent-maintained API supplement covering currently undocumented exports
• $update-api-docs for AI-driven API-reference generation and docstring improvement
• a CI gate immediately after Black and before docs builds or tests
• contribution, PR, pre-commit, Claude, and Copilot guidance for the new workflow
• focused tests proving discovery, Sphinx directive parsing, JSON reporting, generated-page exclusion, and read-only behavior
• removal of the deprecated embodichain.lab.gym.envs.tasks compatibility module and its stale development guidance

The checker deliberately performs no writes. When it reports a missing export, the specialized skill owns generation and validation.

Migration: import official task environments from embodichain_tasks; the legacy embodichain.lab.gym.envs.tasks path is no longer available.

Dependencies: None.

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

Not applicable.

Validation

• black --check --diff --color ./ — 681 files unchanged
• pytest tests/docs -q --confcutdir=tests/docs — 20 passed
• pytest tests/test_release_metadata.py -q — 5 passed
• python docs/scripts/check_api_docs.py — 1027/1027 exports documented
• quick_validate.py — affected agent skills valid
• python -m sphinx -Q -b dummy docs/source docs/build/api-docs-remove-tasks — passed
• the removed compatibility import resolves to no module
• GitHub Actions workflow YAML parsed successfully
• git diff --check — passed

The full simulation/GPU test suite was not run because this change affects documentation tooling, package compatibility guidance, and agent workflows rather than simulation behavior.

Checklist

• I have run the black . command to format the code base.
• I have made corresponding changes to the documentation
• Public API changes are reflected in the API docs (python docs/scripts/check_api_docs.py), if applicable
• I have added tests that prove my fix is effective or that my feature works
• Dependencies have been updated, if applicable.

[greptile-apps]

Greptile Summary

The PR adds a read-only public API documentation coverage checker and integrates it into CI and contributor workflows.

• Discovers static __all__ exports, including declarations inside module-level control flow while excluding nested function and class scopes.
• Parses Sphinx autodoc and autosummary directives and reports missing exports in text or JSON.
• Adds an API-reference supplement, focused checker tests, and agent guidance for maintaining coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/scripts/check_api_docs.py	Adds static public-export discovery, Sphinx directive parsing, coverage comparison, and text/JSON reporting; the previously reported nested-export omission is no longer present.
tests/docs/test_check_api_docs.py	Adds focused regression coverage for branch-scoped exports, nested-scope exclusion, directive parsing, generated-page exclusion, reporting, and read-only behavior.
.github/workflows/main.yml	Runs the API documentation coverage gate after formatting checks in the lint job.
docs/source/api_reference/public_api.rst	Adds the agent-maintained fallback API supplement used to cover exports without curated reference entries.
embodichain/lab/gym/envs/tasks/init.py	Removes the deprecated task compatibility shim that originally exposed the prior branch-scoped __all__ issue.

_{Reviews (3): Last reviewed commit: "refactor(gym): remove legacy task import..." | Re-trigger Greptile}