fix(manpage): render mount synopses and custom command names

[jdx]

Summary

Complete the man-page side of #1393, found while integrating the merged documentation fixes into mise#12889. The man-page renderer builds its own synopsis from the documentation model; that model previously discarded custom subcommand names and unresolved mount fragments.

• Carry declarative mount synopses and custom subcommand names into the documentation model.
• Include mount fragments in root and subcommand synopses without executing discovery.
• Render a detailed section for a command whose only documentation is a mount synopsis.
• Preserve existing man-page formatting and optional/required subcommand behavior.

Please include this in the release tracked by #1389 before mise switches to published dependencies.

Validation: 16 focused man-page tests, including required/optional custom names, root mounts, and mount-only commands whose discovery executable does not exist.

All 785 usage-lib unit tests and Clippy with all features/targets and warnings denied also pass.

AI-generated with Codex.

---

Note

Low Risk
Documentation-only changes to the docs model and man-page renderer; no runtime CLI or discovery behavior.

Overview
The documentation model now keeps subcommand_value_name and declarative mount_synopses (from each mount’s synopsis, without running discovery), which the man-page renderer previously dropped when building its own synopsis.

Man pages use the custom subcommand placeholder instead of hard-coded <COMMAND> / [COMMAND], append mount synopsis fragments to root and per-command usage lines, and emit a subcommand detail section when the only documentation is a mount synopsis. A regression test covers required/optional custom names, root vs nested mounts, and non-executable discovery targets.

^{Reviewed by Cursor Bugbot for commit 37a9747. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation
  • Manpage synopses now support custom subcommand value names.
  • Required and optional subcommand forms are rendered correctly.
  • Mounted command synopses are included in root and nested command documentation.
  • Subcommand detail sections are now shown when mount synopses are available, even without other documented content.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Team

Run ID: 7e4e9477-70f8-41cb-af7b-745eb05f84d1

📥 Commits

Reviewing files that changed from the base of the PR and between f4e22b0 and 37a9747.

📒 Files selected for processing (2)

• lib/src/docs/manpage/renderer.rs
• lib/src/docs/models.rs

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The documentation model now carries custom subcommand value names and mount synopses. Manpage rendering uses both values in command synopses and detail sections. Tests cover required and optional placeholders and root and nested mount synopses.

Changes

Manpage synopsis rendering

Layer / File(s)	Summary
Documentation model metadata lib/src/docs/models.rs	SpecCommand stores subcommand_value_name and mount synopsis strings collected from command mounts.
Manpage synopsis output lib/src/docs/manpage/renderer.rs	Manpage output preserves required or optional custom subcommand placeholders, appends mount synopses, and emits detail sections when mount synopses exist. Tests cover root and nested commands.

Estimated code review effort: 2 (Simple) | ~15 minutes

Merge Risk: ⚪ Minimal · up to 37a97

Manpages now show configured subcommand names and declarative mount synopses, including for commands documented only by mounts. The change is covered for root and nested commands and is ready to merge.

Poem

A rabbit reviews the synopsis trail
With custom names tucked under each sail
Mount notes hop into view
Required and optional forms come through
Root and nested paths leave a tidy tale

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main changes: rendering mount synopses and supporting custom command names in man pages.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}