Skip to content

feat(docs): Add linkable arguments with headerlinks to argparse directive#1010

Merged
tony merged 21 commits intomasterfrom
more-cli-docs
Jan 25, 2026
Merged

feat(docs): Add linkable arguments with headerlinks to argparse directive#1010
tony merged 21 commits intomasterfrom
more-cli-docs

Conversation

@tony
Copy link
Member

@tony tony commented Jan 25, 2026

Summary

  • Add linkable argument definitions to the argparse directive output with headerlinks
  • Arguments get unique IDs based on their option names (e.g., #arg--verbose)
  • Headerlinks appear on hover or when targeted via URL fragment
  • CSS styling with monokai background, proper light/dark mode support
  • Consolidate and clean up CSS selectors for maintainability

Features

  • Linkable arguments: Each argument in the argparse output gets a unique anchor ID
  • Headerlinks: Pilcrow (¶) links appear on hover, positioned outside the argument name
  • URL fragment targeting: Arguments highlight when navigated to via URL hash
  • Light/dark mode: Proper color overrides for both themes

Test plan

  • Build docs with just build-docs
  • Verify headerlinks appear on hover over argument blocks
  • Verify clicking headerlink updates URL and highlights the argument
  • Check light mode styling looks correct
  • Run tests: uv run pytest tests/docs/

@codecov
Copy link

codecov bot commented Jan 25, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.11%. Comparing base (706bd66) to head (4f22db0).
⚠️ Report is 22 commits behind head on master.

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

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
tony added 21 commits January 25, 2026 07:34
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
@tony
Copy link
Member Author

tony commented Jan 25, 2026

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

@tony tony merged commit 3487e8b into master Jan 25, 2026
14 checks passed
@tony tony deleted the more-cli-docs branch January 25, 2026 16:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant