Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 22, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d3d3385
docs(cli): improve docstring formatting for --help and markdown
belloibrahv Oct 22, 2025
d57d048
Merge branch 'main' into fix/cli-docstring-formatting-1108
belloibrahv Oct 22, 2025
efdc553
refactor: simplify blank line handling in extract_description
belloibrahv Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions dev/generate_cli_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down
62 changes: 25 additions & 37 deletions docs/docs/core/cli-commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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:**

Expand All @@ -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:**

Expand Down Expand Up @@ -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:**

Expand All @@ -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
Expand All @@ -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:**

Expand Down
44 changes: 19 additions & 25 deletions python/cocoindex/cli.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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 = (
Expand Down
Loading