"\b" prevents formatting

[nilsvu]

I would like to render click help strings with nice reStructuredText (or markdown) formatting. However, to prevent click from rewrapping lists or code blocks I have to add a "\b" character at the start of the paragraph, like so:

Here's some YAML::

\b
    Greeting: "Hello World"

The "\b" leads sphinx-click to prepend a | character to each line of the paragraph. That's correct RST syntax to prevent rewrapping, but it also prevents rendering the paragraph as a code block. The same happens for simple things like numbered or unnumbered lists.

Does anyone have a solution that allows both, nice formatting in click in the terminal, and in sphinx?

[stephenfin]

The only way that I'm aware of to do this currently is use \f rather than \b, truncating the docstring and allowing you to use full Sphinx formatting for a "larger" help text that won't appear in --help but will appear in your docs. Obviously it's not ideal but it might work if you're planning on including larger snippets and are okay with a less-than-complete --help output.

Other than that, we could add support for a separate attribute on the command other than the docstring attribute (__doc__), where you could include a duplicate "Sphinx'ified" version of the help string. For example:

@click.command()
@click.pass_context
def cli(ctx):
    """My command.

    Here's some YAML:

    \b
        Greeting: "Hello World"
    """
    __sphinx__ = """My command.

    Here's some YAML:

    .. code-block:: yaml

        Greeting: "Hello World"
    """

Obviously this is going to result in a lot of duplication though. Yet another alternative is to add support in click for converting reStructuredText docstrings to plain text. The rst2txt package, which I based on a plain-text writer from Sphinx, could provide a good foundation for doing this conversion. I don't imagine this would be welcome in click core so it'd have to be integrated as a plugin. I'd be happy to house it in sphinx-click though it would obviously need to be integrated to click using a different mechanism.

This isn't a priority for me so I'm not going to pursue either of these personally. I'll happily take a look at any reasonably complete PR folks submit though.