feat(docs): Add linkable arguments with headerlinks to argparse directive#1010
Merged
feat(docs): Add linkable arguments with headerlinks to argparse directive#1010
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1010 +/- ##
=======================================
Coverage 80.11% 80.11%
=======================================
Files 28 28
Lines 2409 2409
Branches 457 457
=======================================
Hits 1930 1930
Misses 356 356
Partials 123 123 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
tony
added a commit
that referenced
this pull request
Jan 25, 2026
Document the new linkable arguments feature with headerlinks, visual styling improvements, and default value badges
tony
added a commit
that referenced
this pull request
Jan 25, 2026
Document the new linkable arguments feature with headerlinks, visual styling improvements, and default value badges
tony
added a commit
that referenced
this pull request
Jan 25, 2026
Document the new linkable arguments feature with headerlinks, visual styling improvements, and default value badges
tony
added a commit
that referenced
this pull request
Jan 25, 2026
Document the new linkable arguments feature with headerlinks, visual styling improvements, and default value badges
Add _generate_argument_id() to create unique IDs from argument names by stripping dashes and joining with hyphens (e.g., "-L" -> "L", ["-v", "--verbose"] -> "v-verbose"). Modify visit_argparse_argument_html() to: - Wrap dt+dd in <div class="argparse-argument-wrapper" id="..."> - Add <a class="headerlink" href="#...">¶</a> for direct linking Modify depart_argparse_argument_html() to: - Wrap default values in <span class="nv"> for styled display - Close the wrapper div
Add id_prefix parameter to render_argument(), render_group(), and render_mutex_group() methods. Update render_group_section() to pass the prefix through to child methods. This enables unique argument IDs per subcommand (e.g., "load-L" vs "shell-L") when multiple argparse directives exist on the same page.
- Background for .argparse-argument-name (like code.literal) - scroll-margin-top for .argparse-argument-wrapper - Headerlink visibility (hidden by default, visible on hover) - :target highlight when navigating via URL fragment - .nv styling in .argparse-argument-meta for default values
Add tests for _generate_argument_id() covering: - Short/long options, positional arguments - Multiple names, empty names, prefix handling Add parametrized HTML rendering tests using NamedTuple: - MockTranslator and render_argument_to_html() helper - Verify wrapper div, headerlink, styled defaults - Test balanced div tags and ID patterns
- Set --color-inline-code-background to #eeeeee in light mode - Use color-mix with 50% white for .argparse-argument-name in light mode
- Use monokai background (#272822) for both light and dark modes - Add dark mode media query for prefers-color-scheme support - Adjust padding to .325rem .6rem and border-radius to .2rem - Add width: fit-content to .argparse-argument-name - Set headerlink color to #9ca0a5 in light mode for dark background - Remove color-mix override (same background for both modes now)
- Use :hover:not(:visited) for headerlink hover states - Set light mode hover color to #cfd0d0
Add background, border-radius, padding, and font-family to .argparse-argument-meta .nv to match inline code appearance.
Replace overrides of Furo's --color-inline-code-background with a custom --argparse-code-background variable (#272822 monokai) to avoid affecting other inline code styling on the site.
- Increase .argparse-argument-name padding to .485rem .875rem - Add .argparse-argument-help with padding-block-start for spacing - Remove unused type: ignore comments in test_nodes.py
- Extract shared font-family into combined .cli-* selector rule - Merge .cli-option-long and .cli-option-short (identical color) - Combine hover and :target headerlink visibility rules - Replace hardcoded #272822 with var(--argparse-code-background)
Use absolute positioning to place the ¶ link outside the dt element to the right, rather than inline. Hover trigger moved to the wrapper element so the link appears when hovering anywhere on the argument block.
Document the new linkable arguments feature with headerlinks, visual styling improvements, and default value badges
Member
Author
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. 🤖 Generated with Claude Code |
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
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.
Summary
¶headerlinks#arg--verbose)Features
Test plan
just build-docsuv run pytest tests/docs/