docs: 全部 8 份文档重写为面向用户的产品文档 - #2
Merged
Merged
Conversation
按 litearm-js README 的排版重排：概述 / 特性 / 安装 / 快速开始 / API 参考 /
注意事项 / 示例 / 开发。描述改成短句直述，去掉括号嵌套补注与警告堆叠。
清除与用户无关的内容：授权/激活整章、pylitearm 提及、旧命名 A1.x-USB、
旧帧布局 4+21N、movel/movec 旧名对照、B1-B4 与"阶段 C"内部代号、
无出处的实测数字（1.48×）。
逐条对着源码与固件修正的实质错误：
- 端口优先级写了 LITEARM_PORT，但 SDK 不读任何环境变量（src/ 里零个
os.environ）；该变量只有 examples/_common.py 用
- kin_bench 不在"单发请求应答"那一组（回执是连续两帧），是 4 个不是 5 个
- connect() 每条失败路径都先 close() 再抛，不留半开会话（原写反）
- 子进程里 close() 仍可调，走轻路径不碰传输层，不会挂死（原写反）
- set_speed 收的是整数百分比且全局持续，set_speed(1) 是 1% 速度不是满速
- home() 须先 enable()（固件 usb_cmd.c:311 → ERR{0x2A,0x03}）
- revert() 不动 flash，重新上电会复活；此后一次 save_params() 会一并抹掉
- get_status_now(0.0) 会主动发 GET_STATUS，一帧未到时抛 MotionTimeoutError
- send_mit/send_mit_all/move_js 的有限性校验在固件侧（usb_cmd.c:485/508/531）
- 去掉无依据的"失能态下 capture() 恒录 0 拍"，移入未验证清单
示例代码修正：move_c 起点须取 .value（直接传 Msg 会抛 InvalidCommandError）、
补 multiprocessing 导入、消除 p1/p2/p3 与 tcp/via_pose 等未定义占位符、
把"with 之后各片段仍在用 arm"讲清楚。
新增 tests/test_doc_examples.py：抽取 8 份文档的全部 python 块，能跑的接到
离线桩上真执行（未交代的占位符会 NameError），签名清单则逐条比对
inspect.signature（参数名、顺序、关键字专用 *、默认值）。已用 6 类注入错误
做过变异测试，全部命中。
配套代码改动：PYLITEARM_LIVE/PYLITEARM_REPO 改名为 LITEARM_LIVE/
LITEARM_REPO（conftest、test_live、env.sh/.ps1/.cmd、run_example.ps1、CI）。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
🎉 This PR is included in version 1.1.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
luomaofu
added a commit
that referenced
this pull request
Sep 29, 2026
* docs: document joint_follow, license and activate Three public entry points had no line in any of the eight documents: joint_follow (added in 97884f3) and license / activate (present since the direct-CDC rewrite, 3d962bb). Record joint_follow in guide section 5.7 and in both READMEs, with the facts read off the firmware rather than the SDK: the accept path clamps q to the soft limits, the firmware slews at its own joint-follow speed table, and the state frame keeps reporting MOVE_MIT_ALL, so the mode field does not tell the host that following is active. Add guide section 5.12 for the license record and the activation call, list license() among the entry points that return no Msg envelope, and add a short README pointer. Verified: 656 passed, 2 skipped (tests/test_doc_examples.py checks every signature and runs every example block against the offline stub). * docs: conform all eight documents to the documentation rules Section 4 of AGENTS.md (added in fed097a, after the documents were rewritten in PR #2) had never been applied to the documents themselves. - Strip the decorative emoji from headings, bullets, status cells and code comments; the wording carries the warning, and the marks do not survive a terminal or a diff. - Join the soft-wrapped list items onto a single line each. Where a bullet carried more than a line's worth of detail, move the detail into the paragraph beside it instead of leaving a 380-character line. - Remove the fourth heading level: the four sub-object sections of the developer guide are now 5.8 to 5.11, and DFU, persistence, read-only properties and licensing move to 5.12 to 5.15. The two README links follow. - State what each document is and who it is for in its first sentence: field troubleshooting and the examples index only described their own layout. - State the working directory for the install and example commands. Every list item now fits within the 130-column limit in .markdownlint.json, so the two rules do not conflict. Verified: 656 passed, 2 skipped, and a scan of all eight files for emoji, fourth-level headings, soft-wrapped bullets and over-long lines reports nothing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
README 的排版重排：概述 / 特性 / 安装 / 快速开始 / API 参考 / 注意事项 / 示例 / 开发。描述改成短句直述，去掉括号嵌套补注与警告堆叠。
清除与用户无关的内容：旧命名 A1.x-USB、
旧帧布局 4+21N、movel/movec 旧名对照、B1-B4 与"阶段 C"内部代号、
无出处的实测数字（1.48×）。
逐条对着源码与固件修正的实质错误：
示例代码修正：move_c 起点须取 .value（直接传 Msg 会抛 InvalidCommandError）、 补 multiprocessing 导入、消除 p1/p2/p3 与 tcp/via_pose 等未定义占位符、 把"with 之后各片段仍在用 arm"讲清楚。
新增 tests/test_doc_examples.py：抽取 8 份文档的全部 python 块，能跑的接到 离线桩上真执行（未交代的占位符会 NameError），签名清单则逐条比对
inspect.signature（参数名、顺序、关键字专用 *、默认值）。已用 6 类注入错误
做过变异测试，全部命中。
配套代码改动：PYLITEARM_LIVE/PYLITEARM_REPO 改名为 LITEARM_LIVE/ LITEARM_REPO（conftest、test_live、env.sh/.ps1/.cmd、run_example.ps1、CI）。