Access untruncated help string

[stephenfin]

There's an open feature request against sphinx-click, asking that we stop ignoring truncation of help strings when generating the documentation. Unfortunately, a quick look suggests this is not currently possible because we don't store the help string before we truncate it.

This RFE ask that we provide some mechanism to access the raw help string. I suspect this will involve either (a) storing the "raw" help string in a different attribute or (b) storing this in the help attribute and truncating on load rather than on store.

[davidism]

I'd prefer option b. There is an eventual goal of making the help formatter much more configurable, and I think doing all formatting at render time would lend itself better to that.

[davidism]

I don't think this should matter for this use case, but should we also delay calling inspect.cleandoc(), which removes leading indentation for multiline strings? It might actually be good for performance anyway. CC @janluke since I just merged #1987, which seems related.

[davidism]

Pointing these out too, although I'm still good with the proposal here. The @command (and @group) decorator does preserve the original docstring by setting command.__doc__ to the decorated function's __doc__. That seems unreliable though since commands created directly will also have __doc__ because objects get their classe's docstring by default. You could also look at command.callback.__doc__, since that will be the decorated function.

[davidism]

help is about the help text, not the full doc. So it makes sense for it to have the truncated version. Documentation tools like Sphinx-Click should be inspecting the callback's doc to output the docs about the callback, not the command's help text.

But on the other hand, I think removing the string processing and cleandoc call in __init__ is important, because it could be significant for startup time not to process help output until it actually needs to be formatted and output.

Maybe the problem is that we're in some intermediate state right now. I want to end up at a place where the help formatting system is much more public and extensible, at which point I'd expect users that need the help text as it would be output to use methods on the formatter to get that, not inspect the command's attribute. We don't have that yet. I think it's probably fine to make this change with the assumption that we will have a better distinction between docs and help output formatting in the future. The majority of users probably aren't affected by it anyway in the mean time.

[davidism]

OK, I think I've convinced myself that having Command.help be the unprocessed help string is ok. Python itself does this with __doc__, it still has all the extra indentation. It's only when you use something like help(func) that it does all the processing. Or Sphinx does its own formatting, etc. Click will match that.