Conversation
Add argparse-usage (https://github.com/acidghost/argparse-usage) to the list of available integrations per #530. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request enhances the project's documentation by introducing a new integration for Python's argparse library. It provides comprehensive details on how to use this integration, making it easier for users to leverage argparse within the system. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
There was a problem hiding this comment.
Code Review
This pull request adds documentation for a new argparse-usage integration for Python. The changes include updating the sidebar navigation, the main integrations list, and adding a new page for the argparse integration. My review focuses on the new documentation page. I've identified a point of confusion in the 'Quick Start' example and suggested a correction. I've also recommended adding an 'Integration Pattern' section to improve the documentation's completeness and align it with other integration guides in the repository.
| python mycli.py --usage-spec | usage generate completion bash | ||
| python mycli.py --usage-spec | usage generate md --out-file docs.md | ||
| python mycli.py --usage-spec | usage generate manpage --out-file mycli.1 |
There was a problem hiding this comment.
The bash examples use a --usage-spec flag, but the Python code in the "Quick Start" section doesn't handle this flag. This can be misleading for users. To make this example correct and self-contained, the --usage-spec flag should be removed from the commands, as the Python script will print the spec upon execution regardless of arguments.
| python mycli.py --usage-spec | usage generate completion bash | |
| python mycli.py --usage-spec | usage generate md --out-file docs.md | |
| python mycli.py --usage-spec | usage generate manpage --out-file mycli.1 | |
| python mycli.py | usage generate completion bash | |
| python mycli.py | usage generate md --out-file docs.md | |
| python mycli.py | usage generate manpage --out-file mycli.1 |
| python mycli.py --usage-spec | usage generate md --out-file docs.md | ||
| python mycli.py --usage-spec | usage generate manpage --out-file mycli.1 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
For consistency with other integration documents (like for clap and cobra) and to provide a more realistic usage example, consider adding an "Integration Pattern" section here. This section would demonstrate how to add a --usage-spec flag to an existing argparse-based CLI application, which is a very common and useful pattern.
Here is a suggested implementation:
## Integration Pattern
A common approach is to add a `--usage-spec` flag that outputs the spec. It's important to check for this flag *before* `parser.parse_args()` is called to avoid validation errors on other arguments.
```python
import argparse
import argparse_usage
import sys
parser = argparse.ArgumentParser(prog='mycli', description='My CLI tool')
parser.add_argument('-v', '--verbose', action='count', default=0)
parser.add_argument('files', nargs='+', help='Files to process')
# Add this check before calling parser.parse_args()
if '--usage-spec' in sys.argv:
spec = argparse_usage.generate(
parser,
name='My CLI',
version='1.0.0',
author='Your Name',
)
print(spec)
sys.exit(0)
args = parser.parse_args()
# ... your CLI logic
print(f"Verbose: {args.verbose}, Files: {args.files}")
```
Then you can pipe the output to `usage`:
```bash
python mycli.py --usage-spec | usage generate completion bash
```There was a problem hiding this comment.
Pull request overview
Adds documentation for the community argparse-usage integration and updates navigation/integration listings accordingly.
Changes:
- Adds a new integration docs page for Python
argparseviaargparse-usage - Updates the integrations index to list
argparseas available (and removes it from “Planned”) - Updates VitePress sidebar navigation to include the new page
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| docs/spec/integrations/argparse.md | New documentation page describing installation/usage/API/feature mapping for argparse-usage. |
| docs/spec/integrations.md | Adds argparse to “Available” integrations and removes it from “Planned”. |
| docs/.vitepress/config.mts | Adds the argparse (Python) link to the sidebar navigation. |
Comments suppressed due to low confidence (1)
docs/spec/integrations/argparse.md:1
- The Quick Start prints the spec unconditionally, but the following examples invoke
python mycli.py --usage-spec(an option that isn’t defined or handled in the snippet). This makes the doc example internally inconsistent. Consider either (a) updating the Python snippet to add and handle a--usage-specflag that prints the generated spec and exits, or (b) removing--usage-specfrom the shell examples and piping the script’s existing output directly.
# argparse (Python)
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #531 +/- ##
==========================================
+ Coverage 77.88% 77.94% +0.05%
==========================================
Files 48 48
Lines 6660 6682 +22
Branches 6660 6682 +22
==========================================
+ Hits 5187 5208 +21
- Misses 1109 1114 +5
+ Partials 364 360 -4 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Greptile SummaryThis PR documents the community integration
Confidence Score: 3/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[User clicks argparse Python in sidebar] --> B{Link type}
B -->|Current: external URL| C[Navigates to github.com/acidghost/argparse-usage\nLeaves docs site]
B -->|Expected: local path| D[Opens /spec/integrations/argparse\nStays in docs site]
D --> E[docs/spec/integrations/argparse.md\nNot present in this PR]
style C fill:#f55,color:#fff
style D fill:#5a5,color:#fff
style E fill:#f55,color:#fff
Last reviewed commit: 4a77b8c |
Co-Authored-By: Claude Opus 4.6 <[email protected]>
Separate the Quick Start (basic spec generation) from the Integration Pattern (wiring up --usage-spec), matching the Cobra docs structure. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Remove the local argparse.md docs page and link directly to the upstream project repository from both the integrations table and sidebar. Co-Authored-By: Claude Opus 4.6 <[email protected]>
| { text: "Cobra (Go)", link: "/spec/integrations/cobra" }, | ||
| { text: "clap (Rust)", link: "/spec/integrations/clap" } | ||
| { text: "clap (Rust)", link: "/spec/integrations/clap" }, | ||
| { text: "argparse (Python)", link: "https://github.com/acidghost/argparse-usage" }, |
There was a problem hiding this comment.
Sidebar links to external URL instead of local docs page
The Cobra and clap sidebar entries both point to local doc pages (/spec/integrations/cobra, /spec/integrations/clap), giving users an in-site documentation experience. The argparse entry instead links to the external GitHub repository, which will navigate users away from the docs site entirely.
The PR description states that a docs/spec/integrations/argparse.md page was created, but that file is not present in this PR — confirming the link should eventually point to /spec/integrations/argparse once that file is added. Either the missing file should be included here, or the sidebar entry should be deferred until that page exists.
| { text: "argparse (Python)", link: "https://github.com/acidghost/argparse-usage" }, | |
| { text: "argparse (Python)", link: "/spec/integrations/argparse" }, |
| | ----------------------------------------------------------- | -------- | --------------------------------------------------------------- | | ||
| | [Cobra](https://github.com/spf13/cobra) | Go | [`cobra_usage`](/spec/integrations/cobra) | | ||
| | [clap](https://crates.io/crates/clap) | Rust | [`clap_usage`](/spec/integrations/clap) | | ||
| | [argparse](https://docs.python.org/3/library/argparse.html) | Python | [`argparse-usage`](https://github.com/acidghost/argparse-usage) | |
There was a problem hiding this comment.
Package column links externally, inconsistent with other integrations
The cobra_usage and clap_usage package cells link to their respective local documentation pages (/spec/integrations/cobra, /spec/integrations/clap). The argparse-usage cell links directly to the external GitHub repository instead. This inconsistency means there is no local documentation page for this integration, while readers following Cobra/clap patterns would expect one.
Since no docs/spec/integrations/argparse.md file was added in this PR, this either needs a companion docs page or the entry should remain a plain link to the external repo with a note clarifying it is a community integration without hosted docs.
## Summary - Replaces the duplicated integration list in `integrations/README.md` with a link to the canonical list at https://usage.jdx.dev/spec/integrations/ - Prevents the two lists from getting out of sync (as happened in #531) Closes #535 ## Test plan - [ ] Verify the link resolves correctly 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk documentation-only change that removes a duplicated list and adds an external link; main risk is link correctness/availability. > > **Overview** > Removes the long, duplicated checklist of planned/available integrations from `integrations/README.md` and replaces it with a single link to the canonical Integrations documentation page to keep the list in one place. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit d7f26ee. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> Co-authored-by: Claude Opus 4.6 <[email protected]>
### 🚀 Features - **(spec)** **breaking** add support for license, before/after help metadata by [@jdx](https://github.com/jdx) in [#542](#542) ### 🐛 Bug Fixes - **(cobra)** escape newlines, tabs, and carriage returns in kdlQuoteAlways by [@thecodesmith](https://github.com/thecodesmith) in [#539](#539) - bump major version for breaking changes in release automation by [@jdx](https://github.com/jdx) in [#544](#544) - add custom_major_increment_regex for breaking change detection by [@jdx](https://github.com/jdx) in [#545](#545) - handle all breaking change commit formats in major bump regex by [@jdx](https://github.com/jdx) in [27e1ab1](27e1ab1) - normalize breaking change commit format in preprocessor by [@jdx](https://github.com/jdx) in [aa72b92](aa72b92) ### 📚 Documentation - add argparse-usage integration by [@jdx](https://github.com/jdx) in [#531](#531) - mark KDL code blocks as KDL and use correct inline-comment `//` by [@muzimuzhi](https://github.com/muzimuzhi) in [#536](#536) - fix include syntax to match implementation by [@jdx](https://github.com/jdx) in [#540](#540) - consolidate integration list to single source by [@jdx](https://github.com/jdx) in [#541](#541) - fix link to integrations by [@muzimuzhi](https://github.com/muzimuzhi) in [#543](#543) ### 🛡️ Security - **(deps)** update dependency eslint to v10 by [@renovate[bot]](https://github.com/renovate[bot]) in [#526](#526) ### 🔍 Other Changes - Added an integration with ruby's OptionParser by [@packrat386](https://github.com/packrat386) in [#533](#533) ### 📦️ Dependency Updates - update actions/setup-node digest to 53b8394 by [@renovate[bot]](https://github.com/renovate[bot]) in [#525](#525) - update jdx/mise-action action to v3 by [@renovate[bot]](https://github.com/renovate[bot]) in [#528](#528) - update rust crate roff to v1 by [@renovate[bot]](https://github.com/renovate[bot]) in [#529](#529) ### New Contributors - @thecodesmith made their first contribution in [#539](#539) - @packrat386 made their first contribution in [#533](#533)
⚠️ **CAUTION: this is a major update, indicating a breaking change!**⚠️ This MR contains the following updates: | Package | Update | Change | |---|---|---| | [usage](https://github.com/jdx/usage) | major | `2.18.2` → `3.2.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>jdx/usage (usage)</summary> ### [`v3.2.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#320---2026-03-23) [Compare Source](jdx/usage@v3.1.0...v3.2.0) ##### 🚀 Features - Support env-backed choices with `choices env=...` by [@​mustafa0x](https://github.com/mustafa0x) in [#​548](jdx/usage#548) ##### 🐛 Bug Fixes - **(zsh)** escape parentheses and brackets in completion descriptions by [@​jdx](https://github.com/jdx) in [#​559](jdx/usage#559) ##### New Contributors - [@​mustafa0x](https://github.com/mustafa0x) made their first contribution in [#​548](jdx/usage#548) ### [`v3.1.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#310---2026-03-22) [Compare Source](jdx/usage@v3.0.0...v3.1.0) ##### 🚀 Features - **(cli)** render all doc-related fields in --help output by [@​jdx](https://github.com/jdx) in [#​554](jdx/usage#554) - **(cli)** support reading spec from stdin via --file - by [@​jdx](https://github.com/jdx) in [#​555](jdx/usage#555) ##### 🐛 Bug Fixes - **(zsh)** remove trailing space from completions and add directory slash by [@​jdx](https://github.com/jdx) in [#​556](jdx/usage#556) - use field assignment for non-exhaustive Spec in benchmarks by [@​jdx](https://github.com/jdx) in [#​552](jdx/usage#552) ##### 📦️ Dependency Updates - update apple-actions/import-codesign-certs digest to [`fe74d46`](jdx/usage@fe74d46) by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​550](jdx/usage#550) - update codecov/codecov-action digest to [`1af5884`](jdx/usage@1af5884) by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​551](jdx/usage#551) - lock file maintenance by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​547](jdx/usage#547) ### [`v3.0.0`](https://github.com/jdx/usage/blob/HEAD/CHANGELOG.md#300---2026-03-13) [Compare Source](jdx/usage@v2.18.2...v3.0.0) ##### 🚀 Features - **(spec)** **breaking** add support for license, before/after help metadata by [@​jdx](https://github.com/jdx) in [#​542](jdx/usage#542) ##### 🐛 Bug Fixes - **(cobra)** escape newlines, tabs, and carriage returns in kdlQuoteAlways by [@​thecodesmith](https://github.com/thecodesmith) in [#​539](jdx/usage#539) - bump major version for breaking changes in release automation by [@​jdx](https://github.com/jdx) in [#​544](jdx/usage#544) - add custom\_major\_increment\_regex for breaking change detection by [@​jdx](https://github.com/jdx) in [#​545](jdx/usage#545) - handle all breaking change commit formats in major bump regex by [@​jdx](https://github.com/jdx) in [27e1ab1](jdx/usage@27e1ab1) - normalize breaking change commit format in preprocessor by [@​jdx](https://github.com/jdx) in [aa72b92](jdx/usage@aa72b92) ##### 📚 Documentation - add argparse-usage integration by [@​jdx](https://github.com/jdx) in [#​531](jdx/usage#531) - mark KDL code blocks as KDL and use correct inline-comment `//` by [@​muzimuzhi](https://github.com/muzimuzhi) in [#​536](jdx/usage#536) - fix include syntax to match implementation by [@​jdx](https://github.com/jdx) in [#​540](jdx/usage#540) - consolidate integration list to single source by [@​jdx](https://github.com/jdx) in [#​541](jdx/usage#541) - fix link to integrations by [@​muzimuzhi](https://github.com/muzimuzhi) in [#​543](jdx/usage#543) ##### 🛡️ Security - **(deps)** update dependency eslint to v10 by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​526](jdx/usage#526) ##### 🔍 Other Changes - Added an integration with ruby's OptionParser by [@​packrat386](https://github.com/packrat386) in [#​533](jdx/usage#533) ##### 📦️ Dependency Updates - update actions/setup-node digest to [`53b8394`](jdx/usage@53b8394) by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​525](jdx/usage#525) - update jdx/mise-action action to v3 by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​528](jdx/usage#528) - update rust crate roff to v1 by [@​renovate\[bot\]](https://github.com/renovate\[bot]) in [#​529](jdx/usage#529) ##### New Contributors - [@​thecodesmith](https://github.com/thecodesmith) made their first contribution in [#​539](jdx/usage#539) - [@​packrat386](https://github.com/packrat386) made their first contribution in [#​533](jdx/usage#533) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My4xMDIuMTAiLCJ1cGRhdGVkSW5WZXIiOiI0My4xMDIuMTAiLCJ0YXJnZXRCcmFuY2giOiJtYWluIiwibGFiZWxzIjpbIlJlbm92YXRlIEJvdCIsImF1dG9tYXRpb246Ym90LWF1dGhvcmVkIiwiZGVwZW5kZW5jeS10eXBlOjptYWpvciJdfQ==-->
Summary
Closes #530
🤖 Generated with Claude Code
Note
Low Risk
Docs-only changes (navigation and tables) with no runtime or security impact.
Overview
Documents the community
argparse-usageintegration by adding it to the Integrations sidebar (docs/.vitepress/config.mts) and to the Available integrations table (docs/spec/integrations.md) with a link to the GitHub repo.Updates the integrations page formatting and removes
argparsefrom the Planned / High Priority list since it is now available.Written by Cursor Bugbot for commit 4a77b8c. This will update automatically on new commits. Configure here.