Document generated SDK docs conventions in CLAUDE.md - #5259
Open
jeremyrose-viam wants to merge 2 commits into
Open
Document generated SDK docs conventions in CLAUDE.md#5259jeremyrose-viam wants to merge 2 commits into
jeremyrose-viam wants to merge 2 commits into
Conversation
…ception in CLAUDE.md
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
viambot
added
the
safe to build
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
2 participants
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.
What this adds
A new "Generated SDK reference docs" section in
CLAUDE.md, covering conventions that only live in code comments or CI config today and cost real time to rediscover:static/include/**/apis/generated/*.md(and-table.md) are generated byupdate_sdk_methods.pyfromsdk_protos_map.csv— don't hand-edit them.prettier-lint.ymlonly checksdocs/**/*.md;markdown-lint.ymlexcludesstatic/outright). Runningprettier --writeon them introduces unrelated reformatting noise.make build-prodstill applies.update_sdk_methods.py's actual Python dependencies (beautifulsoup4,markdownify) aren't inrequirements.txt(that file is for thedocs.ymlindex-sync jobs) — the authoritative list is thepip installline incheck-methods.yml.static/include/<app|components|services|robot>/apis/overrides/protos/<resource>.<ProtoName>.md) supplies the plain-English description, since method signatures/params/examples are scraped live from each SDK's docs site but descriptions aren't. A missing override doesn't fail the build, just leaves a blank description with a coverage-job warning. No README covers this — only comments aroundupdate_sdk_methods.py'swrite_markdown().sdk_protos_map.csv(currently justnavigation, restored as a deprecated orphan page in Restore SLAM and navigation reference pages as deprecated orphan pages #5191) so a real coverage gap isn't mistaken for a bug, or vice versa.Why
Came up repeatedly while resolving stale conflicts on #5186/#5187 (the SDK-method-coverage backlog series) — this is the same context, just made durable and shared instead of re-derived per PR.
Verification
Doc-only change to
CLAUDE.md; no generated content touched.