Optionally support long_description in CLI

[indigoviolet]

🚀 Feature request

Currently, CLI() uses short_description from the parsed docstring

I would like an option to include the long description in the help string.

Motivation

Sometimes there is useful content in the long description which is hidden from the user unless they read the script, or the writer explicitly breaks out that into a help string and sidesteps the docstring parsing functionality, making the docstring less useful for a developer.

Pitch

Add an option to CLI() like include_docstring_long_description.

Alternatives

Use a separate variable and pass it in as CLI(description=...)

[arthurmloureiro]

Hi!
Just to add that I am also finding the need for something like this.

I am trying to get the docstrings from my functions called by CLI to print more than a single line of the docstring but cannot find a proper way of doing it. I need to print a warning for the user which appears in the second line of my docstring (the first is the description) and currently the only way of doing it is having a massive line with a \n in it. This messes up pep8 completely for me...

For example:

def encrypt_main(path_to_sacc: Path_fr,
                 path_to_save: Path_fr = None,
                 keep_original: bool = False) -> None:
    """
    Main function to encrypt a SACC file from the command line.
    [!] WARNING: BY DEFAULT, IT DELETES THE ORIGINAL SACC FILE. [!]

    use the flag --keep_original true to keep the original file.
    """

then later I have:

def main():
  CLI({"datavector": datavector_main,
       "encrypt": encrypt_main,
       },)

and if I call:

mypackage encrypt --help

I only get the following:

Main function to encrypt a SACC file from the command line.

Is there a way to force printing more than a single line?

[mauvilsa]

I have a few ideas to make the help of CLI somehow customizable. Also would be nice to support different levels of details in the help, in the same spirit as described in #377 (comment).

Adding an include_docstring_long_description parameter is too limited, so I prefer to not add something like that until it is clear how to give more options to the developers. Though, I don't think I will work on this in the short time, since there are other more important features to work on.

For the time being, you could patch parse_docstring. For example in your case:

import jsonargparse._optionals

parse_docstring_original = jsonargparse._optionals.parse_docstring

def parse_docstring(component, params=False, logger=None):
    result = parse_docstring_original(component, params, logger)
    if result and getattr(component, "__name__", None) == "encrypt_main":
        result.short_description += " " + result.long_description.split("\n")[0]
    return result

jsonargparse._optionals.parse_docstring = parse_docstring

Do note that the _optional module starts with an underscore because it is supposed to be private and people should not depend on it. If some internal changes are needed, your code would break on some future release. Though, this doesn't mean that these internal changes would happen constantly.