fix: improve bullet list formatting and simplify description logic

- Fix bullet list formatting: each bullet now on separate line
- Simplify extract_description logic as suggested by reviewer
- Intelligently join regular paragraphs while preserving bullet lists
- Maintain all Issue #1108 requirements (backticks, no mid-sentence breaks)

Addresses feedback from PR #1210

Author: belloibrahv

dev/generate_cli_docs.py

@@ -175,7 +175,6 @@ def extract_description(help_text: str) -> str:
     # Find the description between usage and options/commands
     description_lines = []
     in_description = False
-    last_was_empty = False
 
     for line in lines:
         if line.startswith("Usage:"):
@@ -184,35 +183,47 @@ def extract_description(help_text: str) -> str:
         elif line.strip() in ["Options:", "Commands:"]:
             break
         elif in_description:
-            if line.strip():
-                # Non-empty line
-                description_lines.append(line.strip())
-                last_was_empty = False
+            stripped = line.strip()
+            if stripped:
+                description_lines.append(stripped)
             else:
-                # Empty line - only add one blank line to separate paragraphs
-                if description_lines and not last_was_empty:
-                    description_lines.append("")
-                    last_was_empty = True
+                # Blank line - preserve as paragraph separator
+                description_lines.append("")
 
-    # Join lines, treating consecutive lines as same paragraph unless separated by blank line
+    # Join lines intelligently: preserve bullets, join regular text
     result = []
-    current_paragraph = []
+    i = 0
+    while i < len(description_lines):
+        line = description_lines[i]
 
-    for line in description_lines:
+        # Empty line - paragraph separator
         if line == "":
-            # Blank line - end current paragraph
-            if current_paragraph:
-                result.append(" ".join(current_paragraph))
-                current_paragraph = []
-        else:
-            current_paragraph.append(line)
+            result.append("")
+            i += 1
+            continue
 
-    # Add any remaining paragraph
-    if current_paragraph:
-        result.append(" ".join(current_paragraph))
+        # Bullet list item - preserve as-is
+        if line.startswith("-"):
+            result.append(line)
+            i += 1
+            continue
 
-    # Join paragraphs with double newline
-    description = "\n\n".join(result) if result else ""
+        # Regular text - join consecutive non-bullet, non-empty lines
+        paragraph_lines = [line]
+        i += 1
+        while i < len(description_lines):
+            next_line = description_lines[i]
+            # Stop at empty line, bullet, or end
+            if next_line == "" or next_line.startswith("-"):
+                break
+            paragraph_lines.append(next_line)
+            i += 1
+
+        # Join paragraph lines with space
+        result.append(" ".join(paragraph_lines))
+
+    # Join with single newline
+    description = "\n".join(result) if result else ""
     return escape_html_tags(description)  # Escape HTML tags for MDX compatibility
 
 
@@ -221,6 +232,11 @@ def generate_command_docs(cmd: click.Group) -> str:
 
     markdown_content = []
 
+    # Disable lint warnings for about "first line in file should be a top level heading"
+    # We intentionally start with a level 2 heading below, as this file is imported into another file.
+    markdown_content.append("<!-- markdownlint-disable MD041 -->")
+    markdown_content.append("")
+
     # Add top-level heading to satisfy MD041 linting rule
     markdown_content.append("## Subcommands Reference")
     markdown_content.append("")

docs/docs/core/cli-commands.md

@@ -1,11 +1,15 @@
+<!-- markdownlint-disable MD041 -->
+
 ## Subcommands Reference
 
 ### `drop`
 
+
 Drop the backend setup for flows.
 
 Modes of operation: 1. Drop all flows defined in an app: `cocoindex drop <APP_TARGET>` 2. Drop specific named flows: `cocoindex drop <APP_TARGET> [FLOW_NAME...]`
 
+
 **Usage:**
 
 ```bash
@@ -23,14 +27,20 @@ cocoindex drop [OPTIONS] [APP_TARGET] [FLOW_NAME]...
 
 ### `evaluate`
 
+
 Evaluate the flow and dump flow outputs to files.
 
 Instead of updating the index, it dumps what should be indexed to files. Mainly used for evaluation purpose.
 
-`APP_FLOW_SPECIFIER`: Specifies the application and optionally the target flow. Can be one of the following formats: - `path/to/your_app.py` - `an_installed.module_name` - `path/to/your_app.py:SpecificFlowName` - `an_installed.module_name:SpecificFlowName`
+`APP_FLOW_SPECIFIER`: Specifies the application and optionally the target flow. Can be one of the following formats:
+- `path/to/your_app.py`
+- `an_installed.module_name`
+- `path/to/your_app.py:SpecificFlowName`
+- `an_installed.module_name:SpecificFlowName`
 
 `:SpecificFlowName` can be omitted only if the application defines a single flow.
 
+
 **Usage:**
 
 ```bash
@@ -49,12 +59,14 @@ cocoindex evaluate [OPTIONS] APP_FLOW_SPECIFIER
 
 ### `ls`
 
+
 List all flows.
 
 If `APP_TARGET` (`path/to/app.py` or a module) is provided, lists flows defined in the app and their backend setup status.
 
 If `APP_TARGET` is omitted, lists all flows that have a persisted setup in the backend.
 
+
 **Usage:**
 
 ```bash
@@ -71,12 +83,14 @@ cocoindex ls [OPTIONS] [APP_TARGET]
 
 ### `server`
 
+
 Start a HTTP server providing REST APIs.
 
 It will allow tools like CocoInsight to access the server.
 
 `APP_TARGET`: `path/to/app.py` or `installed_module`.
 
+
 **Usage:**
 
 ```bash
@@ -103,10 +117,12 @@ cocoindex server [OPTIONS] APP_TARGET
 
 ### `setup`
 
+
 Check and apply backend setup changes for flows, including the internal storage and target (to export to).
 
 `APP_TARGET`: `path/to/app.py` or `installed_module`.
 
+
 **Usage:**
 
 ```bash
@@ -124,14 +140,19 @@ cocoindex setup [OPTIONS] APP_TARGET
 
 ### `show`
 
+
 Show the flow spec and schema.
 
 `APP_FLOW_SPECIFIER`: Specifies the application and optionally the target flow. Can be one of the following formats:
 
-- `path/to/your_app.py` - `an_installed.module_name` - `path/to/your_app.py:SpecificFlowName` - `an_installed.module_name:SpecificFlowName`
+- `path/to/your_app.py`
+- `an_installed.module_name`
+- `path/to/your_app.py:SpecificFlowName`
+- `an_installed.module_name:SpecificFlowName`
 
 `:SpecificFlowName` can be omitted only if the application defines a single flow.
 
+
 **Usage:**
 
 ```bash
@@ -150,10 +171,12 @@ cocoindex show [OPTIONS] APP_FLOW_SPECIFIER
 
 ### `update`
 
+
 Update the index to reflect the latest data from data sources.
 
 `APP_FLOW_SPECIFIER`: `path/to/app.py`, module, `path/to/app.py:FlowName`, or `module:FlowName`. If `:FlowName` is omitted, updates all flows.
 
+
 **Usage:**
 
 ```bash