Documentation ignores the \b characters in docstrings

As is documented in click here, the docstrings for click commands are expected to contain \b characters before a paragraph which should not be made to wrap.

This allows better formatting of docstrings in the help output, without this it is impossible to make any kind of formatting of the help such as point form lists which describe the meaning of each click.Choice() option.

This works well for click’s help output, but is also broken for the click-man generated man pages, and for sphinx-click generated html (although the man pages are slightly less broken than the html).

See this example of the breakage and compare with the corresponding help output below:

Usage: bst show [OPTIONS] TARGET

  Show elements in the pipeline

  By default this will only show the specified element, use the --deps
  option to show an entire pipeline.

  FORMAT
  ~~~~~~
  The --format option controls what should be printed for each element,
  the following symbols can be used in the format string:

      %{name}     The element name
      %{key}      The abbreviated cache key (if all sources are consistent)
      %{full-key} The full cache key (if all sources are consistent)
      %{state}    cached, buildable, waiting or inconsistent
      %{config}   The element configuration
      %{vars}     Variable configuration
      %{env}      Environment settings
      %{public}   Public domain data

  The value of the %{symbol} without the leading '%' character is understood
  as a pythonic formatting string, so python formatting features apply,
  examle:

      build-stream show target.bst --format \
          'Name: %{name: ^20} Key: %{key: ^8} State: %{state}'

  If you want to use a newline in a format string in bash, use the '$'
  modifier:

      build-stream show target.bst --format \
          $'---------- %{name} ----------\n%{vars}'

Options:
  -d, --deps [all|build|run]  Optionally specify a dependency scope to show
  --order [stage|alpha]       Staging or alphabetic ordering of dependencies
  -f, --format FORMAT         Format string for each element
  -a, --arch TEXT             The target architecture (default: x86_64)
  --variant TEXT              A variant of the specified target
  --help                      Show this message and exit.

[gtristan]

@stephenfin I guess I just went on a tangent on what might be the ideal solution…

So, basically I have three outputs of my doc strings:

• application --help output
• man pages generated with the click_man thing
• documentation generated with sphinx-click

With the application help output, I can do some alignments and tables and stuff, like:

    \b
    Values for the --frobtype argument
        foo        Frob it with foo
        bar        Bar it from any frobbing
        baz        Frob it baz

So I can create aligned output in the additional text I write in the documentation body and am not limited to the alignment provided by argument options; but in html this alignment is lost because of lack of monospace fonts.

I think it makes sense with the current approach to force monospace fonts in the rendered docs, otherwise there is no way to use any alignment in your help text.

Looking at the reverse approach

With man pages we have more freedom of expression than with help output, and with HTML we have even more freedom.

The current approach with click is to write a very, very simple format for help output (the format is just text with a special meaning of the \b character); and then use that same format to generate man pages and html documentation.

Things would make more sense the other way around:

• Click command docstrings should support markdown
• Click itself should honor the markdown on a best effort basis when printing --help output
• The man pages can do a better job of honoring the markdown
• The html can do an even better job of honoring the markdown

Just saying, this would be a much nicer experience 😃

[stephenfin]

Fixed in the above commit.