Skip to content

Unexpected interaction with click rewrapping #291

Open
@adamtheturtle

Description

@adamtheturtle

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    C: stakeholderRelates to docformatter stakeholder requested behaviorP: enhancementFeature that is outside the scope of PEP 257U: lowA relatively low urgency issue

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions