Add writing-style standards; backtick inline code in help prose - #166
Open
lai-bianca wants to merge 1 commit into
Open
Add writing-style standards; backtick inline code in help prose#166lai-bianca wants to merge 1 commit into
lai-bianca wants to merge 1 commit into
Conversation
New docs/agents/writing-style.md: inline code (flags, commands, paths, env vars) is always backticked in help text and docstrings. The hosted docs generate their CLI reference from help --json, where a bare --flag renders as an em dash plus the flag name; backticks also make literals unambiguous for agents. tests/test_help_style.py enforces the flag rule across the help surface's prose fields (topic bodies exempt: they are pre-formatted terminal layouts). Wraps the ~50 existing bare mentions and regenerates the help.json snapshot. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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.
Adds
docs/agents/writing-style.md(prose standards plus one enforced rule: inline code in help prose is always backticked) andtests/test_help_style.py, which fails CI naming any bare--flagin the help surface's prose fields. Wraps the ~50 existing bare mentions in the source help strings and regenerates thehelp.jsonsnapshot.Why: the hosted docs now generate their CLI reference from
help --json, and their renderer displays a bare--flagin prose as an em dash plus the flag name. Backticks also give agents unambiguous literal boundaries, and they are already this CLI's help-text voice.Deliberately exempt: topic bodies and usage lines (pre-formatted terminal layouts and copy-pasteable commands, where backticks would corrupt the rendering).
Full suite passes (667 tests),
ruffandtyclean. Referenced from CLAUDE.md and CONTRIBUTING.md.🤖 Generated with Claude Code