ewels
Newline control
When printing help messages, the paragraph structure gets mangled by rich_click in the sense that separation between paragraphs is not respected. The following MWE illustrates what I mean.
import rich_click as click
click.rich_click.USE_RICH_MARKUP = True
# click.rich_click.USE_MARKDOWN = True
@click.command()
@click.option("-d", "--dummy", help="Does nothing")
def mwe(dummy: str):
"""This is a simple echo clone.
This paragraph should be separated from the summary by one line.
This sentence should also have a gap of one blank line with the previous one.
"""
if dummy:
click.echo(dummy)
mwe()
The output is as follows. The first instance is the output of this MWE directly, the second is when USE_MARKDOWN is uncommented.
Shouldn't white paragraph separations be left alone?
System info
- OS: Arch linux
- Terminal: Konsole 21.12.3 (connected to Windows Prompt via SSH)
- python: 3.10.4
- rich_click: 1.2.1
- rich: 12.0.1
- click: 8.0.4
This behaviour is kind of intentional. Because we can have quite wide terminal rendering with rich, it makes sense that we want to render paragraphs in a justified manner. If you're writing your docstrings with PEP 8 with 79 character line lengths and only 60 chars to play with you're going to have a tonne of whitespace off to the right.
Collapsing single line breaks and replacing double line breaks with single was my response to this, and whilst it's crude I'm not sure that I can really think of a better way to do it:
https://github.com/ewels/rich-click/blob/cb612ff7804a28f52b7c2afe3e3e1a45623c21fb/src/rich_click/rich_click.py#L167-L174
With the markdown rendering I basically don't do anything and it should render in the same way as any other markdown text.
Currently there are two ways around this - double the number of newlines you have in your docstrings or use the \b click modifier.
What is your suggestion for changing the current behaviour? That newlines should be collapsed but double-newlines should be kept as double-newlines?
That newlines should be collapsed but double-newlines should be kept as double-newlines?
Re-reading those click rewrapping docs (which I don't think I had seen at the time that I wrote this code) I'm thinking that you're probably right. As click was already doing the newlines thing then maybe we should mimic the same behaviour.
For default text handling anyway, I'm not super keen on changing how Markdown parsing works.
What is your suggestion for changing the current behaviour? That newlines should be collapsed but double-newlines should be kept as double-newlines?
For me the main point is that a single line break in the docstring is simply a way to keep to code tidy (and not having a 500-characters long line), so it makes sense that rich_click removes them to fit the terminal windows, because that's the whole point of using rich, letting it handle layout stuff. A new line doesn't really influence how the text reads.
OTOH, a double line is something the person writing the docstring does to better structure the help text. There is a reason why it's put in a certain place. And as you said, click also respects these, so also from a technical standpoint, if rich_click aims to almost be a drop-in replacement for the click import, then this behavior should be replicated.
Honestly, for the markdown case, I think it's enough to simply split summary and verbose help text, but without touching the verbose text, as that should be fully interpreted as a markdown document.
There is a reason why it's put in a certain place.
Sure, I think we're agreeing on the intent and overall behaviour. That's why rich-click already keeps them - just with a single newline instead of the original double. It's the same behaviour as the rich markdown rendering.
I think you're probably right that most people will expect the blank spacing newline though. It means less compact output but we can probably add a configuration variable to maintain the current behaviour for people who prefer it (like me 😅, at least with long help texts). It's the only way I can think of to make single newlines without the blank possible.
Is there any progress on this issue? I'm quoting an example input file like this:
For example, the following is a valid group list file:
\b
# Physics 101
## Group A
Drew Ferrell (800057) [second year]
Amanda James (379044)
Antonio Morris (804407) [skips thursdays]
but because rich-click is eating newlines, it turns into:
For example, the following is a valid group list file:
# Physics 101
## Group A
Drew Ferrell (800057) [second year]
Amanda James (379044)
Antonio Morris (804407) [skips thursdays]
so the example input file does not stand out from the main help text (there are more paragraphs of text leading up to this example).
Not really sorry @davidfokkema. However in your case it's fairly easy to solve - it's not eating all newlines, just collapsing double to single. So if you double up then it works as expected:
For example, the following is a valid group list file:
\b
# Physics 101
## Group A
Drew Ferrell (800057) [second year]
Amanda James (379044)
Antonio Morris (804407) [skips thursdays]
Renders as:
For example, the following is a valid group list file:
# Physics 101
## Group A
Drew Ferrell (800057) [second year]
Amanda James (379044)
Antonio Morris (804407) [skips thursdays]
I will not be touching the default behavior of rich-click. But, I think it is reasonable to include a formatting feature such as COLLAPSE_DOUBLE_NEWLINES (name is tentative) which is by default set to False, so users have more control over this behavior. I will look into this.
