DexForce/EmbodiChain / .agents/skills/update-api-docs
update-api-docs
VerifiedGenerate or update EmbodiChain Sphinx API documentation for public Python exports. Use when the API docs checker or CI reports missing __all__ exports, after adding or changing public APIs, or when asked to fill, generate, or synchronize API-reference pages and their descriptions.
Update API Docs
Generate useful API documentation for every public export reported by the
read-only checker. Treat static __all__ declarations as the public API
contract and preserve existing hand-written documentation.
Workflow
-
Run the checker in machine-readable mode:
python docs/scripts/check_api_docs.py --format jsonExit status 1 is expected when exports are missing. Read the JSON report; if
missing_countis zero, report that the docs are aligned and stop. -
Group missing entries by module. Read each reported source file and inspect the exported definition, signature, type annotations, and docstring. Locate existing API pages with:
rg -n "automodule:: <module>|currentmodule:: <module>" docs/source/api_reference -
Choose the documentation location:
- Add the export to an existing curated module page when one exists. Follow that page's headings, autosummary groups, and detailed autodoc directives.
- Document a package-level re-export under its public import path, not only under the implementation module.
- If no suitable curated page exists, add or extend the module section in
docs/source/api_reference/public_api.rst. This file is an agent-maintained fallback, not checker output. Keep fallback module headings sorted by import path and entries in their declared__all__order to minimize diff churn.
-
Write documentation that explains the API:
- Add the export to the appropriate
autosummaryblock. - Add the matching
autoclass,autofunction,autodata, or other detailed directive when the surrounding page provides detailed entries. - Add a concise section overview when names alone do not explain the group.
- If the source docstring is missing or too vague for autodoc, improve it
with a meaningful summary and Google-style
Args,Returns, andRaisessections where applicable. - Derive descriptions from the implementation and tests. Do not invent behavior, examples, guarantees, or parameter semantics.
- Add the export to the appropriate
-
Keep the change scoped to documentation. Do not alter runtime behavior, signatures, or
__all__merely to silence the checker. Do not replace curated prose with generic generated text or add placeholders such as "part of the public API." -
Rerun the checker until it reports zero missing exports:
python docs/scripts/check_api_docs.py -
Run Black on every changed Python file, then validate the documentation workflow:
pytest tests/docs/test_check_api_docs.py -q --confcutdir=tests/docs python -m sphinx -b dummy docs/source docs/build/api-docs-checkWhen source docstrings were changed, also run focused tests for those modules. Fix new Sphinx warnings caused by the edit; distinguish them from unrelated pre-existing warnings.
Completion Report
Report the documented import paths, the pages or docstrings updated, and the validation results. If an export cannot be documented accurately from the repository, identify the exact missing semantic information instead of guessing.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |