python plugin lib removes line breaks from doc string for help function

[renepickhardt]

As mentioned in #2139 the line breaks are removed from the doc string of plugin functions when the doc string is depicted as the help string. I thought this was a mistake and wanted to fix it. However looking at the code it looks desperately:

lightning/contrib/pylightning/lightning/plugin.py

Line 245 in 0321d79

doc = re.sub('\n+', ' ', doc)

Is the rational behind this to keep the API doc clean? For the funds plugin it would be much nicer if the list with all the line breaks would stay like that list.

I opened an issue instead of a PR since this line seems very desperately put there.

[cdecker]

The rationale for this change was that we use this help message in the command line result for lightning-cli help, which gets escaped and thus we end up printing a couple of \n in the help message. A more durable and clean change could be to keep the newlines and then do some post-processing in the lightning-cli instead when using human readable format (split lines and indent each one so it is displayed correctly).

[renepickhardt]

I guess you are talking about the code block following this line?
https://github.com/ElementsProject/lightning/blob/master/cli/lightning-cli.c#L56

why is this replace actually being made in the first place?

[cdecker]

That's in order to make the human readable output more readable by indenting the help text below the command

[NishantBansal2003]

Hi @cdecker,
I was working on this issue and noticed that the doc variable is not being used anywhere:

lightning/contrib/pyln-client/pyln/client/plugin.py

Lines 941 to 961 in 2f64283

	doc = inspect.getdoc(method.func)
	if not doc:
	self.log(
	'RPC method \'{}\' does not have a docstring.'.format(
	method.name
	)
	)
	doc = "Undocumented RPC method from a plugin."
	doc = re.sub('\n+', ' ', doc)
	# For compatibility with lightningd prior to 24.08, we must
	# provide a description. Ignored by 24.08 onwards,
	description = method.description
	if description is None:
	description = ""
	methods.append({
	'name': method.name,
	'usage': method.get_usage(),
	'description': description,
	})

.
Additionally, when I use the plugin and run the lightning-cli help command, I get the following output for the funds plugin:

funds [unit] \\nLists the total funds the lightning node owns off- and on-chain in {unit}.\\n{unit} can take the following values:\\ns, satoshi, satoshis to represent satoshis\\nb, bit, bits to represent bits\\nm, milli, btc to represent milliBitcoin\\nB, bitcoin, btc to represent Bitcoins\\nWhen not using Satoshis (default), the values are rounded off.

Would it make sense to open a separate issue to address both the unused doc variable and the formatting issues in the help output?

[cdecker]

Yeah, let's create a new issue. The usage of the doc string has changed substantially over the last years, and I'm not sure I know how it's used at the moment.