Process functions: Parse docstring to set input port help attribute

[sphuber]

Fixes #5896
Fixes #5918

The docstring-parser package is used to parse the docstring of a
process function if one is present. If the parsing is successful the
description of the function arguments is used to set the help
attribute of the corresponding InputPort that is added to the
dynamically generated process specification.

This is especially useful when the process function is exposed in a
wrapping workchain as now the description of the inputs is inherited
from the docstring and becomes immediately available on the process spec
of the workchain. This allows a user to inspect the inputs description
without having to go look at the source code of the function.

[sphuber]

This is ready for review. @unkcpz @chrisjsewell @superstar54

[unkcpz]

Thanks @sphuber. I am curious if there are many params and by accident the user carelessly put a typo for the docstring of one parameter, if the whole parsing will fail and show empty or the parser still works for valid params docstring? For instance what will happened to the docstring below?

    @calcfunction
    def function(param_a, param_b, param_c):  # pylint: disable=unused-argument
        """Some documentation.
        :param param_a: Some description.
        :param param_b Fantastic docstring.
        """

[unkcpz]

Suggested change

	monkeypatch.setattr(docstring_parser, 'parse', lambda x: raise_exception())
	monkeypatch.setattr(docstring_parser, 'parse', lambda _: raise_exception())

[sphuber]

Thanks @sphuber. I am curious if there are many params and by accident the user carelessly put a typo for the docstring of one parameter, if the whole parsing will fail and show empty or the parser still works for valid params docstring? For instance what will happened to the docstring below?

In your example, the parser thinks the parameter definitions are actually "just" the long description:

In [14]: parsed = parse(function.__doc__)

In [15]: parsed.params
Out[15]: []

In [16]: parsed.long_description
Out[16]: ':param param_a: Some description.\n:param param_b Fantastic docstring.'

In [17]: parsed.short_description
Out[17]: 'Some documentation.'

So the parser doesn't raise an exception nor emit a warning. This is kind of tricky, since I am not sure how to reliably detect whether the docstring was "correctly" parsed. Just checking whether parsed.params is empty won't help, because maybe the docstring didn't provide any params, and so it was not a parser failure. If you have ideas, please let me know.

Currently a warning is only printed if the parsing really excepts, but I have tried creating docstrings that cause the parser to except and I haven't managed. I think it is designed to never except. So not sure how to detect whether parsing was successful.

[unkcpz]

Currently a warning is only printed if the parsing really excepts, but I have tried creating docstrings that cause the parser to except and I haven't managed. I think it is designed to never except. So not sure how to detect whether parsing was successful.

Thanks for checking. I think warnings for docstring would frighten users, at least I personally didn't write proper docstring especially aways, so maybe just show nothing.

[unkcpz]

The lambda is not a mandatory change. All looks to me.