diff --git a/dev/generate_cli_docs.py b/dev/generate_cli_docs.py index 0ab2da13..2647c7bf 100644 --- a/dev/generate_cli_docs.py +++ b/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 diff --git a/docs/docs/core/cli-commands.md b/docs/docs/core/cli-commands.md index a7d6cba4..95011b46 100644 --- a/docs/docs/core/cli-commands.md +++ b/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 ` - 2. Drop specific named flows: `cocoindex drop [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:** diff --git a/python/cocoindex/cli.py b/python/cocoindex/cli.py index 26c994c1..45a6b9ea 100644 --- a/python/cocoindex/cli.py +++ b/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 = (