Make CLI docstrings / metadata render well in both --help and generated md file #1110
Conversation
dev/generate_cli_docs.py
Outdated
| def backquote_terms(text: str) -> str: | ||
| """ | ||
| Wrap code-style terms (ALL_CAPS, example module names, file paths, angle brackets, .Name) in backticks. | ||
| """ | ||
| # Backquote ALL_CAPS terms | ||
| text = re.sub(r"\b([A-Z_]{2,})\b", r"`\1`", text) | ||
| # Backquote example modules and paths (simple heuristics) | ||
| text = re.sub(r"\b([a-zA-Z0-9_\.]+\.py)\b", r"`\1`", text) | ||
| text = re.sub(r"\b([a-zA-Z0-9_]+\.[a-zA-Z0-9_]+)\b", r"`\1`", text) | ||
| # Backquote things like :SpecificFlowName, :AnythingName | ||
| text = re.sub(r"(:[a-zA-Z0-9_]+Name\b)", r"`\1`", text) | ||
| # Backquote things in angle brackets (e.g., <APP_TARGET>) | ||
| text = re.sub(r"(<[A-Z_]+>)", r"`\1`", text) | ||
| return text |
There was a problem hiding this comment.
I see you already updated docstrings / attributes in cli.py, which add backquotes explicitly. Actually I think that is the better approach (more control, less magic, and backquotes also makes --help output clearer). Then do we still need this magic here?
There was a problem hiding this comment.
Removed this approach. Please see the new commit
| \b | ||
| APP_FLOW_SPECIFIER: Specifies the application and optionally the target flow. | ||
| `APP_FLOW_SPECIFIER`: Specifies the application and optionally the target flow. |
There was a problem hiding this comment.
I think the \b needs to be kept, otherwise these bulleted lines below will be rewrapped.
https://click.palletsprojects.com/en/stable/documentation/#escaping-click-s-wrapping
(or did you see otherwise when running --help?)
dev/generate_cli_docs.py
Outdated
| description = "\n\n".join(description_lines) if description_lines else "" | ||
| # Collapse multiple blank lines into a single blank line | ||
| description = "\n".join(description_lines) if description_lines else "" | ||
| description = re.sub(r"\n{2,}", "\n", description) |
There was a problem hiding this comment.
Will this over strip?
e.g. if we have two paragraphs like this in docstring:
This is paragraph 1.
This is paragraph 2.
The blank line should be there in the markdown too, to make these two separate paragraphs.
There was a problem hiding this comment.
Resolved this by using description = re.sub(r"\n{3,}", "\n\n", description)
Removed the backquote_terms function and its usage in formatting options and descriptions.
|
Hi @S3lc0uth can you also rerun the script to update the generated md file and add to the PR? |
|
@S3lc0uth is this PR still active? thanks |
|
@badmonster0 yes I just need to update the md file |
3 participants
Updated CLI command docstrings in cli.py:
Updated markdown generation script (generate_cli_docs.py):
Reference : Make CLI docstrings / metadata render well in both
--helpand generated md file #1108