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?