docs(cli): improve docstring formatting for --help and markdown (#1210)

* docs(cli): improve docstring formatting for --help and markdown

- Add backticks around technical terms (APP_TARGET, APP_FLOW_SPECIFIER, paths, modules)
- Fix docstring formatting in cli.py for better rendering in both terminal and markdown
- Simplify extract_description() logic in generate_cli_docs.py (join with \n, let Markdown handle formatting)
- Fix bullet list formatting: each bullet now on separate line
- Eliminate redundant blank lines that break sentences mid-paragraph
- Ensure consistent, professional rendering across all CLI commands

Fixes #1108

* refactor: simplify blank line handling in extract_description

Remove unnecessary last_was_empty tracking logic. Click's help formatter
already produces well-formatted output, so we only need to:
- Append non-empty stripped lines
- Preserve blank lines for paragraph separation (if we have content)

This addresses reviewer feedback and makes the code cleaner and more maintainable.

Author: belloibrahv

dev/generate_cli_docs.py

@@ -182,10 +182,15 @@ def extract_description(help_text: str) -> str:
             continue
         elif line.strip() in ["Options:", "Commands:"]:
             break
-        elif in_description and line.strip():
-            description_lines.append(line.strip())
-
-    description = "\n\n".join(description_lines) if description_lines else ""
+        elif in_description:
+            stripped = line.strip()
+            if stripped:
+                description_lines.append(stripped)
+            elif description_lines:  # Preserve blank line only if we have content
+                description_lines.append("")
+
+    # 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

@@ -7,11 +7,10 @@
 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
@@ -32,25 +31,18 @@ cocoindex drop [OPTIONS] [APP_TARGET] [FLOW_NAME]...
 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
-
-:SpecificFlowName can be omitted only if the application defines a single
+`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
@@ -71,13 +63,12 @@ cocoindex evaluate [OPTIONS] APP_FLOW_SPECIFIER
 
 List all flows.
 
-If APP_TARGET (path/to/app.py or a module) is provided, lists flows defined
+If `APP_TARGET` (`path/to/app.py` or a module) is provided, lists flows
+defined in the app and their backend setup status.
 
-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:**
 
@@ -99,7 +90,8 @@ 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.
+`APP_TARGET`: `path/to/app.py` or `installed_module`.
+
 
 **Usage:**
 
@@ -129,10 +121,10 @@ 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.
+`APP_TARGET`: `path/to/app.py` or `installed_module`.
+
 
 **Usage:**
 
@@ -154,22 +146,18 @@ cocoindex setup [OPTIONS] APP_TARGET
 
 Show the flow spec and schema.
 
-APP_FLOW_SPECIFIER: Specifies the application and optionally the target
-
+`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
+- `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
@@ -190,9 +178,9 @@ cocoindex show [OPTIONS] APP_FLOW_SPECIFIER
 
 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
+`APP_FLOW_SPECIFIER`: `path/to/app.py`, module, `path/to/app.py:FlowName`,
+or `module:FlowName`. If `:FlowName` is omitted, updates all flows.
 
-module:FlowName. If :FlowName is omitted, updates all flows.
 
 **Usage:**
 

python/cocoindex/cli.py

@@ -136,11 +136,9 @@ def ls(app_target: str | None) -> None:
     """
     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.
     """
     persisted_flow_names = flow_names_with_setup()
     if app_target:
@@ -188,16 +186,15 @@ def show(app_flow_specifier: str, color: bool, verbose: bool) -> None:
     """
     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:
 
     \b
-      - 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.
+    `:SpecificFlowName` can be omitted only if the application defines a single flow.
     """
     app_ref, flow_ref = _parse_app_flow_specifier(app_flow_specifier)
     _load_user_app(app_ref)
@@ -314,7 +311,7 @@ def setup(app_target: str, force: bool, reset: bool) -> None:
     """
     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.
+    `APP_TARGET`: `path/to/app.py` or `installed_module`.
     """
     app_ref = _get_app_ref_from_specifier(app_target)
     _load_user_app(app_ref)
@@ -433,8 +430,7 @@ def 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.
     """
     app_ref, flow_name = _parse_app_flow_specifier(app_flow_specifier)
     _load_user_app(app_ref)
@@ -492,18 +488,16 @@ def 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.
 
     \b
-    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.
+    `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.
     """
     app_ref, flow_ref = _parse_app_flow_specifier(app_flow_specifier)
     _load_user_app(app_ref)
@@ -619,7 +613,7 @@ def server(
 
     It will allow tools like CocoInsight to access the server.
 
-    APP_TARGET: path/to/app.py or installed_module.
+    `APP_TARGET`: `path/to/app.py` or `installed_module`.
     """
     app_ref = _get_app_ref_from_specifier(app_target)
     args = (