Skip to content
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.

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

Unexpected interaction with click rewrapping #291

Open
adamtheturtle opened this issue Oct 8, 2024 · 0 comments
Open

Unexpected interaction with click rewrapping #291

adamtheturtle opened this issue Oct 8, 2024 · 0 comments
Labels
C: stakeholder Relates to docformatter stakeholder requested behavior P: enhancement Feature that is outside the scope of PEP 257 U: low A relatively low urgency issue

Comments

@adamtheturtle
Copy link

adamtheturtle commented Oct 8, 2024

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.

@github-actions github-actions bot added the fresh This is a new issue label Oct 8, 2024
@weibullguy weibullguy added P: enhancement Feature that is outside the scope of PEP 257 C: stakeholder Relates to docformatter stakeholder requested behavior and removed fresh This is a new issue labels Oct 9, 2024
@github-actions github-actions bot added U: low A relatively low urgency issue labels Oct 9, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C: stakeholder Relates to docformatter stakeholder requested behavior P: enhancement Feature that is outside the scope of PEP 257 U: low A relatively low urgency issue
Projects
None yet
Development

No branches or pull requests

2 participants