Unexpected interaction with click rewrapping
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 598
- Forks
- 93
- PR merge metrics
- No merged PRs in 30d
Description
Thank you for this project.
I am trying to get it to work with a CLI I maintain which uses Click.
Click generates help text for CLI commands from method docstrings.
Click rewraps text based on the width of the terminal, to a maximum of 80 characters.
In my case, this is not suitable as I have a long URL in a help text.
I therefore use Click's functionality to prevent rewrapping.
This involves using a \b escape marker.
If we take the example in the Click documentation:
@click.command()
def cli():
"""First paragraph.
This is a very long second paragraph and as you
can see wrapped very early in the source text
but will be rewrapped to the terminal width in
the final output.
\b
This is
a paragraph
without rewrapping.
And this is a paragraph
that will be rewrapped again.
"""
This renders as:
Usage: example.py [OPTIONS]
First paragraph.
This is a very long second paragraph and as you can see wrapped very early
in the source text but will be rewrapped to the terminal width in the final
output.
This is
a paragraph
without rewrapping.
And this is a paragraph that will be rewrapped again.
Options:
--help Show this message and exit.
However, docformatter moves the \b escape marker, so that the docstring is as so:
@click.command()
def cli():
"""First paragraph.
This is a very long second paragraph and as you can see wrapped very
early in the source text but will be rewrapped to the terminal width
in the final output.
\b This is a paragraph without rewrapping.
And this is a paragraph that will be rewrapped again.
"""
This changes the rewrapping, so the help output is not as desired:
Usage: example.py [OPTIONS]
First paragraph.
This is a very long second paragraph and as you can see wrapped very early
in the source text but will be rewrapped to the terminal width in the final
output.
This is a paragraph without rewrapping.
And this is a paragraph that will be rewrapped again.
Options:
--help Show this message and exit.
In my case, this breaks a link.
I have a workaround - to tell Click not to interpret the help text from the docstring. However, I hope that this can be resolved in docformatter.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the Click example from the issue and compare its help output before and after docformatter runs. Trace how the standalone \b marker is handled, then verify that formatting preserves it as a separate paragraph and keeps the following text unrewrapped.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100