Enhance documentation and CLI help text formatting#55
Conversation
- Added best practices for Click CLI help text formatting in CLAUDE.md, including key principles, formatting templates, and common issues. - Updated README.md to include smart PR detection and troubleshooting sections for authentication issues and common errors. - Improved command documentation in cli.py, fetch.py, reply.py, and resolve.py with consistent formatting and examples. - Adjusted test assertions in various CLI tests to reflect updated documentation and ensure accuracy in help text outputs. These changes aim to improve user guidance and enhance the overall clarity of the CLI documentation.
WalkthroughThis unholy mess is a documentation overhaul. Help text and docstrings for CLI commands ( Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CLI
participant HelpText
User->>CLI: Run command with --help
CLI->>HelpText: Fetch formatted docstring
HelpText-->>CLI: Return structured, pretty help text
CLI-->>User: Display improved help output
Possibly related PRs
Poem
✨ Finishing Touches
🧪 Generate Unit Tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
src/toady/commands/resolve.py (1)
128-132:⚠️ Potential issueF-string mixed with plain literal => SyntaxError at import-time
f"\n{action_symbol} {action_present} {len(target_threads)} " "thread(s)..."An f-string cannot be implicitly concatenated with a normal string literal.
Python raises aSyntaxError: cannot mix f-string and non f-string literals.
This will break every runtime path that importsresolve.py.Proposed fix – keep a single f-string:
-f"\n{action_symbol} {action_present} {len(target_threads)} " "thread(s)..." +f"\n{action_symbol} {action_present} {len(target_threads)} thread(s)..."Apply the same pattern anywhere else this “f-string + literal” form appears.
🧹 Nitpick comments (6)
CLAUDE.md (1)
195-255: Fuckin’ awesome doc section but watch list punctuation.
You’ve nailed the “Click CLI Help Text Formatting Best Practices” section, but your numbered list hyphens should be en dashes (–) per LanguageTool.🧰 Tools
🪛 LanguageTool
[typographical] ~237-~237: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...ode examples** with proper indentation (4-6 spaces) - Use quotes consistently: ...(HYPHEN_TO_EN)
src/toady/commands/fetch.py (1)
55-67: This docstring is goddamn solid but duplicate “Default:” bullets.
You’ve got two bullets starting with Default: (auto-detect vs only unresolved). Rename the second to avoid confusing shit (e.g., “Unresolved only by default”).src/toady/cli.py (1)
29-49: Non-ASCII bullets may garble on minimal terminalsThe docstring now uses the • U+2022 bullet. On headless CI boxes or Windows cmd, these occasionally render as
?or break alignment. Consider plain-or*for maximum portability.
Purely cosmetic but easy to future-proof.tests/integration/cli/test_reply_cli.py (1)
561-574: Hard-coded command in assertionsThe updated guidance
toady fetch --format prettyis duplicated in multiple assertions. If the flag set changes again, every test will need editing. Consider extracting expected snippets to a constant helper so future changes touch one place.tests/unit/test_cli.py (1)
376-380: Guard against more section additions
expected_sectionsis manually enumerated. When new sections are added the test will fail even though the CLI is fine. Optional: loop through only required sections or assert subset to reduce churn.README.md (1)
259-291: Nitpick: include “the” for smoother phrasing
Consider adding the definite article before flags and options in this block:
- “use the
--debugflag”- “Use the
--limitoption to reduce API calls”🧰 Tools
🪛 LanguageTool
[uncategorized] ~276-~276: You might be missing the article “the” here.
Context: ...ug Mode - Set TOADY_DEBUG=1 or use--debugflag for detailed error info - ...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~287-~287: You might be missing the article “the” here.
Context: ...comment IDs ### Rate Limiting - Use--limitoption to reduce API calls - ...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~288-~288: Possible missing preposition found.
Context: ...limit` option** to reduce API calls - Add delays between operations in scripts ...(AI_HYDRA_LEO_MISSING_TO)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (12)
CLAUDE.md(1 hunks)README.md(2 hunks)src/toady/cli.py(1 hunks)src/toady/commands/fetch.py(1 hunks)src/toady/commands/reply.py(5 hunks)src/toady/commands/resolve.py(3 hunks)tests/integration/cli/test_fetch_cli.py(1 hunks)tests/integration/cli/test_reply_cli.py(3 hunks)tests/integration/cli/test_resolve_cli.py(1 hunks)tests/integration/real_api/test_end_to_end_workflows.py(1 hunks)tests/unit/commands/test_reply.py(1 hunks)tests/unit/test_cli.py(2 hunks)
🧰 Additional context used
🧬 Code Graph Analysis (1)
tests/unit/test_cli.py (1)
src/toady/cli.py (1)
cli(23-91)
🪛 LanguageTool
CLAUDE.md
[typographical] ~237-~237: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...ode examples** with proper indentation (4-6 spaces) - Use quotes consistently: ...
(HYPHEN_TO_EN)
README.md
[uncategorized] ~276-~276: You might be missing the article “the” here.
Context: ...ug Mode - Set TOADY_DEBUG=1 or use --debug flag for detailed error info - ...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~287-~287: You might be missing the article “the” here.
Context: ...comment IDs ### Rate Limiting - Use --limit option to reduce API calls - ...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~288-~288: Possible missing preposition found.
Context: ...limit` option** to reduce API calls - Add delays between operations in scripts ...
(AI_HYDRA_LEO_MISSING_TO)
⏰ Context from checks skipped due to timeout of 90000ms (5)
- GitHub Check: test (windows-latest, 3.12)
- GitHub Check: test (windows-latest, 3.11)
- GitHub Check: test (windows-latest, 3.9)
- GitHub Check: test (windows-latest, 3.10)
- GitHub Check: integration-test
🔇 Additional comments (11)
src/toady/commands/fetch.py (1)
84-103: Examples block looks tight. Approving.
The Examples section follows the\bformatting guidelines perfectly.tests/integration/cli/test_resolve_cli.py (1)
369-372: Corrected help header check.
Updated test to assert capitalized “Examples:” matches the new help formatting.tests/integration/cli/test_fetch_cli.py (1)
132-136: Capitalized header assertion is on point.
Switching from “EXAMPLES:” to “Examples:” aligns with doc updates.tests/unit/commands/test_reply.py (1)
501-508: Updated help content expectations.
The test now checks for the corrected fetch syntaxtoady fetch --format prettyand the decorated “📚 EXAMPLES:” header, matching the updated reply docstring.tests/integration/cli/test_reply_cli.py (1)
280-281: Ensure help header casing really isExamples:The assertion now looks for the capitalised header. Double-check that the underlying Click help actually emits
Examples:(notEXAMPLES:orexamples:) on all locales; otherwise this test will be noisy.tests/unit/test_cli.py (1)
63-66: Section headers now case-sensitiveThe unit test assumptions (
Prerequisites:, etc.) match the new docstring. Good catch – confirms docs/tests stay in sync.tests/integration/real_api/test_end_to_end_workflows.py (1)
334-343: Graceful empty-output handling looks solidThe try/except JSON parse plus
strip()check avoids spurious failures when the interactive fetch returns nothing. Nice resilience tweak.src/toady/commands/reply.py (3)
56-57: Verify updated fetch example in ID help
The example now usestoady fetch --format pretty—please confirm that this flag is supported by your Click option definitions and that existing tests have been updated accordingly.
85-85: Ensure consistent troubleshooting example syntax
The second help step also usestoady fetch --format pretty. Double-check that both instances align with your CLI’s legacy and new formatting options, and update tests if needed.
511-579: Docstring formatting improvements approved
The explicit\bmarkers, clear section ordering, and uniform indentation follow the best-practice guidelines in CLAUDE.md. Examples and error codes are well-structured and consistent.README.md (1)
90-102: Smart PR Detection section looks good
The new section clearly outlines auto-detection behavior and override usage with well-formatted code blocks.
1 participant
These changes aim to improve user guidance and enhance the overall clarity of the CLI documentation.
Summary by CodeRabbit
Documentation
Tests