cli: Separate category labels from "examples:" in help output

tony · tony · commit 76ad7a7a194d · 2026-01-11T04:43:49.000-06:00
Category headings now use clean format without "examples:" suffix:

Before: "Field-scoped search examples:"
After:  "Field-scoped search:"

- build_description() formats headings as "{heading}:" not "{heading} examples:"
- Formatter recognizes category headings within examples blocks
- Add tests for category heading colorization
- Update extract_examples_from_help() to match new format
diff --git a/src/tmuxp/_internal/colors.py b/src/tmuxp/_internal/colors.py
@@ -836,6 +836,7 @@ def build_description(
     example_blocks : sequence of (heading, commands) tuples
         Each tuple contains an optional heading and a sequence of example commands.
         If heading is None, the section is titled "examples:".
+        If heading is provided, it becomes the section title (without "examples:").
 
     Returns
     -------
@@ -849,7 +850,7 @@ def build_description(
     'My tool.\n\nexamples:\n  mytool run'
 
     >>> build_description("My tool.", [("sync", ["mytool sync repo"])])
-    'My tool.\n\nsync examples:\n  mytool sync repo'
+    'My tool.\n\nsync:\n  mytool sync repo'
 
     >>> build_description("", [(None, ["cmd"])])
     'examples:\n  cmd'
@@ -864,7 +865,7 @@ def build_description(
     for heading, commands in example_blocks:
         if not commands:
             continue
-        title = "examples:" if heading is None else f"{heading} examples:"
+        title = "examples:" if heading is None else f"{heading}:"
         lines = [title]
         lines.extend(f"  {command}" for command in commands)
         sections.append("\n".join(lines))
diff --git a/src/tmuxp/cli/_formatter.py b/src/tmuxp/cli/_formatter.py
@@ -129,11 +129,18 @@ def _fill_text(self, text: str, width: int, indent: str) -> str:
             leading = stripped_line[:leading_length]
             content = stripped_line[leading_length:]
             content_lower = content.lower()
-            is_section_heading = (
-                content_lower.endswith("examples:") and content_lower != "examples:"
+            # Recognize example section headings:
+            # - "examples:" starts the examples block
+            # - "X examples:" or "X:" are sub-section headings within examples
+            is_examples_start = content_lower == "examples:"
+            is_category_in_block = (
+                in_examples_block and content.endswith(":") and not content[0].isspace()
             )
+            is_section_heading = (
+                content_lower.endswith("examples:") or is_category_in_block
+            ) and not is_examples_start
 
-            if is_section_heading or content_lower == "examples:":
+            if is_section_heading or is_examples_start:
                 formatted_content = f"{theme.heading}{content}{theme.reset}"
                 in_examples_block = True
                 expect_value = False
diff --git a/tests/cli/test_formatter.py b/tests/cli/test_formatter.py
@@ -102,6 +102,48 @@ def test_fill_text_without_theme_plain_text(self) -> None:
         assert "\033[" not in result
         assert "tmuxp load myproject" in result
 
+    def test_fill_text_category_headings_colorized(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Category headings within examples block are colorized."""
+        monkeypatch.delenv("NO_COLOR", raising=False)
+        colors = Colors(ColorMode.ALWAYS)
+        formatter_cls = create_themed_formatter(colors)
+        formatter = formatter_cls("tmuxp")
+
+        # Test category heading without "examples:" suffix
+        text = "examples:\n  tmuxp ls\n\nMachine-readable output:\n  tmuxp ls --json"
+        result = formatter._fill_text(text, 80, "")
+
+        # Both headings should be colorized
+        assert "\033[" in result
+        assert "examples:" in result
+        assert "Machine-readable output:" in result
+        # Commands should also be colorized
+        assert "tmuxp" in result
+        assert "--json" in result
+
+    def test_fill_text_category_heading_only_in_examples_block(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Category headings are only recognized within examples block."""
+        monkeypatch.delenv("NO_COLOR", raising=False)
+        colors = Colors(ColorMode.ALWAYS)
+        formatter_cls = create_themed_formatter(colors)
+        formatter = formatter_cls("tmuxp")
+
+        # Text before examples block should not be colorized as heading
+        text = "Some heading:\n  not a command\n\nexamples:\n  tmuxp load"
+        result = formatter._fill_text(text, 80, "")
+
+        # "Some heading:" should NOT be colorized (it's before examples block)
+        # "examples:" and the command should be colorized
+        lines = result.split("\n")
+        # First line should be plain (no ANSI in "Some heading:")
+        assert "Some heading:" in lines[0]
+
 
 class TestHelpOutputIntegration:
     """Integration tests for help output colorization."""
diff --git a/tests/cli/test_help_examples.py b/tests/cli/test_help_examples.py
@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import argparse
-import re
 import subprocess
 
 import pytest
@@ -55,19 +54,33 @@ def extract_examples_from_help(help_text: str) -> list[str]:
 
     Examples
     --------
-    >>> text = "load examples:\n  tmuxp load myproject\n\npositions:"
+    >>> text = "load:\n    tmuxp load myproject\n\npositions:"
     >>> extract_examples_from_help(text)
     ['tmuxp load myproject']
 
     >>> text2 = "examples:\n  tmuxp debug-info\n\noptions:"
     >>> extract_examples_from_help(text2)
     ['tmuxp debug-info']
+
+    >>> text3 = "Field-scoped search:\n    tmuxp search window:editor"
+    >>> extract_examples_from_help(text3)
+    ['tmuxp search window:editor']
     """
     examples = []
     in_examples = False
     for line in help_text.splitlines():
-        # Match "examples:" or "load examples:" etc.
-        if re.match(r"^(\S+\s+)?examples?:$", line, re.IGNORECASE):
+        # Match example section headings:
+        # - "examples:" (default examples section)
+        # - "load examples:" or "load:" (category headings)
+        # - "Field-scoped search:" (multi-word category headings)
+        # Exclude argparse sections like "positional arguments:", "options:"
+        stripped = line.strip()
+        is_section_heading = (
+            stripped.endswith(":")
+            and stripped not in ("positional arguments:", "options:")
+            and not stripped.startswith("-")
+        )
+        if is_section_heading:
             in_examples = True
         elif in_examples and line.startswith("  "):
             cmd = line.strip()
