Skip to content

docs: document the new interfaces and conform the eight documents - #15

Merged
luomaofu merged 2 commits into
mainfrom
docs/document-interfaces-and-conform
Sep 29, 2026
Merged

luomaofu merged 2 commits into
mainfrom
docs/document-interfaces-and-conform

Conversation

@luomaofu

Copy link
Copy Markdown
Contributor

Summary

Two things are missing from the documentation, and this PR fixes both.

The interfaces are undocumented. Arm.joint_follow (merged in #14) and Arm.license /
Arm.activate (present since the direct-CDC rewrite, 3d962bb) had no entry in any of the eight
documents. docs/DEVELOPER_GUIDE.md §4 tells the reader which entry points deliberately return
no Msg envelope; license() was missing from that list too.

The documents had never been audited against the documentation rules. §4 of AGENTS.md
entered the standard in #6 (fed097a), while the eight documents were rewritten in #2 — so the
rules that now govern them were written after them.

Changes

Interface documentation:

  • Record joint_follow in guide §5.7 and in both READMEs. The notes come from the firmware
    source (litearm-stm32 master 391e612, clean tree), not from the SDK alone: the payload is
    16N bytes with no tau, the firmware clamps q to the soft limits and kp/kd to its MIT
    limits, dq is a velocity reference rather than a rate limit, the accept path returns
    0x03 / 0x04 / 0x06, and the state frame keeps reporting MOVE_MIT_ALL, so the mode
    field does not tell the host that following is active.
  • Add guide §5.15 for the license record and the activation call, and a short README pointer.
  • List license() among the entry points that return no Msg envelope.

Conformance to the §4 documentation rules:

  • Strip the decorative emoji from headings, bullets, status cells and code comments. The wording
    carries the warning; 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, the detail moves into the paragraph beside it rather than staying as a
    380-character line.
  • Remove the fourth heading level. The four sub-object sections of the developer guide become
    §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 configured in .markdownlint.json, so the
standard and the linter no longer conflict.

Testing

python3 -m pytest -q
656 passed, 2 skipped in 60.71s

tests/test_doc_examples.py parses every python block in the eight documents, verifies each
signature entry against inspect.signature, and executes every example block against the
offline stub. The two blocks added here account for the two extra cases over the 654 that passed
before this work.

A separate scan of all eight files reports no emoji, no fourth-level heading, no soft-wrapped
list item and no line over 130 columns.

Issues

None — no issue tracks this.

Not in this PR

  • The English paragraphs wrap at about 100 columns, not the 80 the rules suggest. Re-flowing
    them would rewrite roughly 190 lines with no change in content, so it is left out.
  • The offline stub (src/litearm/testing.py) sends 0x08 through its catch-all else: _ack,
    so the firmware's two new error codes for that command ({0x08,0x01} short payload,
    {0x08,0x02} non-finite values) and its enable gate have no criterion anywhere; the coverage
    test only asserts that the command id went out. Worth a separate change.

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).
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.
@luomaofu
luomaofu merged commit 5f53b6e into main Sep 29, 2026
2 checks passed
@luomaofu
luomaofu deleted the docs/document-interfaces-and-conform branch September 29, 2026 08:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant