show-extensions: fix hook-doc rendering (heading marker + btrfs docs)

[igorpecovnik]

Problem

The generated Extension Hooks page had two rendering bugs:

1. Broken TOC + giant blockquote. The docs formatter printed the hook summary as > <first inline-doc line>. When that line started with # (e.g. btrfs_root_add_subvolumes, whose comment opens # custom post btrfs...), it became > # text — a level-1 heading inside a blockquote. It rendered oversized and broke the page's table of contents for every hook after it.
2. Raw-shell hook docs. The two btrfs_root_add_subvolumes[_fstab] hook docs were shell comments + example commands, not markdown, so they rendered as run-together text.

Fix

• lib/functions/cli/cli-show-extensions.sh: strip a leading # from the summary so it can never become a heading; guard the body so summary-only hooks don't emit a trailing blank. Bodies stay prose (with inline code), as intended.
• lib/functions/image/partitioning.sh: rewrite the two btrfs hook docs as a prose summary + description + a fenced example.

Hook doc comments are markdown and should be written as such; this makes the two offenders conform and stops one of them from breaking the page.

bash -n clean. Verified: full 65-hook TOC, clean prose rendering.

Summary by CodeRabbit

• Documentation
  • Improved formatting of extension documentation output.
  • Updated Btrfs partitioning hook guidance with clearer descriptions and fenced examples.
  • Improved handling of optional documentation content and spacing.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 79bc6371-0c3f-4126-9173-772a9a3d7dbb

📥 Commits

Reviewing files that changed from the base of the PR and between cc76b90 and adf2168.

📒 Files selected for processing (2)

• lib/functions/cli/cli-show-extensions.sh
• lib/functions/image/partitioning.sh

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

---

📝 Walkthrough

Walkthrough

The CLI documentation output now normalizes heading markers and conditionally separates body lines. Btrfs extension hook comments now include structured descriptions and fenced examples.

Changes

Extension Documentation

Layer / File(s)	Summary
Format CLI documentation output lib/functions/cli/cli-show-extensions.sh	SHOW_EXTENSIONS=docs removes leading # markers before blockquote rendering and adds a blank line only when additional body lines exist.
Document Btrfs extension hooks lib/functions/image/partitioning.sh	The subvolume and fstab hooks now describe their timing, responsibilities, and examples in structured documentation.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to adf21

This change fixes hook documentation formatting without introducing an actionable merge-blocking risk; it is merge-ready after normal checks and review.

Suggested reviewers: iav

🚥 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 2 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main changes: fixing hook documentation rendering and updating Btrfs documentation.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/show-extensions-docs-fenced-body

---

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.}