docs(cli): improve docstring formatting for --help and markdown
#1210
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
Author
|
@georgeh0 @badmonster0, kindly help me review when you have time. Thank You |
belloibrahv
changed the title
--help and markdown
georgeh0
reviewed
Oct 22, 2025
docs/docs/core/cli-commands.md
Outdated
| `APP_FLOW_SPECIFIER`: Specifies the application and optionally the target flow. Can be one of the following formats: | ||
|
|
||
| - an_installed.module_name | ||
| - `path/to/your_app.py` - `an_installed.module_name` - `path/to/your_app.py:SpecificFlowName` - `an_installed.module_name:SpecificFlowName` |
dev/generate_cli_docs.py
Outdated
Comment on lines
186
to
215
| elif in_description: | ||
| if line.strip(): | ||
| # Non-empty line | ||
| description_lines.append(line.strip()) | ||
| last_was_empty = False | ||
| 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 | ||
|
|
||
| # Join lines, treating consecutive lines as same paragraph unless separated by blank line | ||
| result = [] | ||
| current_paragraph = [] | ||
|
|
||
| for line in description_lines: | ||
| if line == "": | ||
| # Blank line - end current paragraph | ||
| if current_paragraph: | ||
| result.append(" ".join(current_paragraph)) | ||
| current_paragraph = [] | ||
| else: | ||
| current_paragraph.append(line) | ||
|
|
||
| description = "\n\n".join(description_lines) if description_lines else "" | ||
| # Add any remaining paragraph | ||
| if current_paragraph: | ||
| result.append(" ".join(current_paragraph)) | ||
|
|
||
| # Join paragraphs with double newline | ||
| description = "\n\n".join(result) if result else "" |
Member
There was a problem hiding this comment.
I think it'll just work if we simply join description lines with \n (i.e. 1 \n instead of 2), without any filtering logic above.
Because Markdown already allows single line break within a paragraph.
This means as long as the docstring for cli.py is written in the Markdown-compatible way, it'll just work.
The logic here can be simplified a lot, and the incorrect format for bullets (as I comment below) will also be fixed.
Does this make sense?
Contributor
Author
There was a problem hiding this comment.
@georgeh0 - Yes, this makes perfect sense! You're absolutely right.
I was over-engineering the solution by trying to intelligently join lines and create paragraphs. Your suggestion to simply join with \n and let Markdown handle it naturally is much cleaner and will fix both issues:
- Bullet list formatting - Preserving the original line breaks will keep bullets on separate lines
- Simpler logic - Trusting Markdown's natural behavior instead of complex paragraph detection
I'll simplify the extract_description() function as you suggested and ensure the docstrings in cli.py are Markdown-compatible. This will resolve the formatting issues.
Thank you for the clear feedback!
belloibrahv
force-pushed
the
fix/cli-docstring-formatting-1108
branch
from
1489701 to
81736f3
Compare
belloibrahv
added a commit
to belloibrahv/cocoindex
that referenced
this pull request
Oct 22, 2025
- 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 cocoindex-io#1108 requirements (backticks, no mid-sentence breaks) Addresses feedback from PR cocoindex-io#1210
belloibrahv
force-pushed
the
fix/cli-docstring-formatting-1108
branch
from
9ac6352 to
9f2b9e2
Compare
belloibrahv
added a commit
to belloibrahv/cocoindex
that referenced
this pull request
Oct 22, 2025
- 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
georgeh0
reviewed
Oct 22, 2025
- 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 cocoindex-io#1108
belloibrahv
force-pushed
the
fix/cli-docstring-formatting-1108
branch
from
648eafe to
d3d3385
Compare
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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
generate_cli_docs.pyFixes #1108