Allow whitespace before ${cmd_name}.

[andrewshadura]

It's not immediately obvious to the plug-in writers ${cmd_name} must be on the very first line of the docstring, and docstrings often begin and end with """ on its own line:

"""
${cmd_name}: Foobarise baz

This command makes baz more foobarish.

${cmd_usage}
${cmd_option_list}
"""

[marcus-h]

On 2017-09-02 04:31:53 -0700, Andrew Shadura wrote: -- Commit Summary -- * Allow whitespace before ${cmd_name}.

Why do you need this? I just checked the existing osc commands and they stick to this convention... so I assume you need this for a plugin? If so, would "fixing" the plugin be an option?

[andrewshadura]

I thought the explanation in the pull request would be enough… I don't think it's wrong to put """ on its own line, and I actually prefer that style, so why not allow that? Is there any reason to strictly require no whitespace before ${cmd_name}?

[andrewshadura]

Right, I suspect you may have not seen it, as I have added the explanation after I created the pull request, and you seem to be using GitHub's email interface. Let me repost it for you:

It's not immediately obvious to the plug-in writers ${cmd_name} must be on the very first line of the docstring, and docstrings often begin and end with """ on its own line:

"""
${cmd_name}: Foobarise baz

This command makes baz more foobarish.

${cmd_usage}
${cmd_option_list}
"""

[andrewshadura]

PEP 257 says:

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line. The summary line may be on the same line as the opening quotes or on the next line. The entire docstring is indented the same as the quotes at its first line (see example below).

[marcus-h]

On 2017-09-02 18:27:47 +0000, Andrew Shadura wrote: Right, I suspect you may have not seen it, as I have added the explanation *after* I created the pull request, and you seem to be using GitHub's email interface. Let me repost it for you:

Yep, I haven't seen your explanation. Thanks!

> It's not immediately obvious to the plug-in writers `${cmd_name}` must be on the very first line of the docstring, and docstrings often begin and end with `"""` on its own line:

If you really need this feature, we should make the patch "consistent", because with the current version the leading whitespaces are still present when running "osc cmd --help".

[andrewshadura]

Right, I'll have a look and resubmit.

[dmach]

Wouldn't be better to do doc = doc.lstrip() before if doc ...?
It is more efficient (running lstrip() only once) and also covers a situation (unlikely one) that the docstring contains only whitespaces.

[dmach]

This change makes sense to me and it sits in the backlog for too long.
Merging in.