fix: simplify extract_description logic and fix bullet formatting

- Simplify description extraction to use single newline joins
- Fix bullet list formatting: each bullet now on separate line
- Remove complex paragraph joining logic (45 lines -> 28 lines)
- Let Markdown handle formatting naturally
- Maintain all Issue cocoindex-io#1108 requirements (backticks, no redundant blank lines)

Addresses feedback from @georgeh0 in PR cocoindex-io#1210

Author: belloibrahv

dev/generate_cli_docs.py

@@ -175,6 +175,7 @@ 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:"):
@@ -186,44 +187,15 @@ def extract_description(help_text: str) -> str:
             stripped = line.strip()
             if stripped:
                 description_lines.append(stripped)
+                last_was_empty = False
             else:
-                # Blank line - preserve as paragraph separator
-                description_lines.append("")
+                # Blank line - preserve as paragraph separator, avoid duplicates
+                if description_lines and not last_was_empty:
+                    description_lines.append("")
+                    last_was_empty = True
 
-    # Join lines intelligently: preserve bullets, join regular text
-    result = []
-    i = 0
-    while i < len(description_lines):
-        line = description_lines[i]
-
-        # Empty line - paragraph separator
-        if line == "":
-            result.append("")
-            i += 1
-            continue
-
-        # Bullet list item - preserve as-is
-        if line.startswith("-"):
-            result.append(line)
-            i += 1
-            continue
-
-        # 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 ""
+    # Simply join with single newline - let Markdown handle paragraph formatting naturally
+    description = "\n".join(description_lines) if description_lines else ""
     return escape_html_tags(description)  # Escape HTML tags for MDX compatibility
 
 

docs/docs/core/cli-commands.md

@@ -4,10 +4,11 @@
 
 ### `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...]`
+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:**
@@ -27,18 +28,19 @@ 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.
+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`
 
-`:SpecificFlowName` can be omitted only if the application defines a single flow.
+`:SpecificFlowName` can be omitted only if the application defines a single
+flow.
 
 
 **Usage:**
@@ -59,12 +61,13 @@ 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` (`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.
+If `APP_TARGET` is omitted, lists all flows that have a persisted setup in
+the backend.
 
 
 **Usage:**
@@ -83,7 +86,6 @@ cocoindex ls [OPTIONS] [APP_TARGET]
 
 ### `server`
 
-
 Start a HTTP server providing REST APIs.
 
 It will allow tools like CocoInsight to access the server.
@@ -117,8 +119,8 @@ cocoindex server [OPTIONS] APP_TARGET
 
 ### `setup`
 
-
-Check and apply backend setup changes for flows, including the internal storage and target (to export to).
+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`.
 
@@ -140,17 +142,18 @@ 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:
+`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.
+`:SpecificFlowName` can be omitted only if the application defines a single
+flow.
 
 
 **Usage:**
@@ -171,10 +174,10 @@ 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.
+`APP_FLOW_SPECIFIER`: `path/to/app.py`, module, `path/to/app.py:FlowName`,
+or `module:FlowName`. If `:FlowName` is omitted, updates all flows.
 
 
 **Usage:**