Multiline docstring in help with parameters and their descriptions

[MartinXPN]

I'm using the latest version of Fire as of now and was wondering if it's possible to display a multiline docstring in help instead of concatenating it to one line. Also is there a way of displaying the available params and their descriptions in the help screen?

Example program:

# main.py
import fire

class MyCLI:
    def create(name, surname):
    """
    Method to create a user \n
    And some second line to describe some specific cases.
    And some third line that could be concatenated with the second one
    :param name name of the user
    :param surname surname of the user
    :raises ValueError if user with this name and surname already exist
    :returns: unique id of the created user
    """
    ...

    def remove(id):
    """
    Removes user given the id
    :id unique id to identify the user
    :raises ValueError if there is no user with the specified id
    """
    ...


if __name__ == '__main__':
    cli = MyCLI()
    fire.Fire(cli)

Expected help:

main.py -h

NAME
    main.py -

SYNOPSIS
    main.py COMMAND

COMMANDS
    COMMAND is one of the following:

     create
    Method to create a user
    And some second line to describe some specific cases. And some third line that could be concatenated with the second one

     remove
       Removes user given the id

Example command help (more specific)

main.py create -h

NAME
    main.py create - Method to create a user

SYNOPSIS
    main.py create NAME SURNAME

DESCRIPTION
    Method to create a user
    And some second line to describe some specific cases. And some third line that could be concatenated with the second one
    --name: name of the user
    --surname: surname of the user
    raises ValueError if user with this name and surname already exist
    returns: unique id of the created user

POSITIONAL ARGUMENTS
    NAME 
    SURNAME

NOTES
    You can also use flags syntax for POSITIONAL ARGUMENTS

[dbieber]

Agreed on multi-line docstrings.

This is particularly important if people use whitespace for formatting in their docstrings, such as including usage examples.

The param descriptions should be showing up in the help in a separate section from the description. If that's not showing up, that's a bug. The return and raises information is being parsed but isn't being displayed yet, but should be in a later version.

[MartinXPN]

Yes I think right now the params formatted like

    :param name name of the user
    :param surname surname of the user

aren't getting displayed in the help screen.

[dbieber]

Multi-line docstrings issue is resolved.

As for the params, it works if you 1) add the missing self args to your methods (or mark them as @staticmethod) and 2) include a closing colon around your param directives.

E.g. if you update your code to this:

class MyCLI:
  def create(self, name, surname):
    """
    Method to create a user \n
    And some second line to describe some specific cases.
    And some third line that could be concatenated with the second one
    :param name: name of the user
    :param surname: surname of the user
    :raises ValueError if user with this name and surname already exist
    :returns: unique id of the created user
    """
    pass

  def remove(self, id):
    """
    Removes user given the id
    :param id: unique id to identify the user
    :raises ValueError if there is no user with the specified id
    """
    pass

fire.Fire(MyCLI())

Then these work:

MyCLI.py  create -h
MyCLI.py  remove -h

Of course we want our docstring parser to be as lenient as reasonably possible, so if we're able to support parsing args from your docstrings without compromising our ability to parse other docstrings, then we will. So, I'll leave the issue open for more flexibly/leniently parsing docstrings.

[okada8]

Hello, I need the configuration information of all cloud servers under my account and all the areas where cloud servers can be built. Please provide examples of the corresponding API and python code.

[dbieber]

Hi okada8, I think your request is misplaced. This is an issue thread for Python Fire.

[nlarusstone]

Is there any way to display the arguments from the docstring, even if they're not an explicitly named parameter in the function signature? In the example before, we accept bar as part of kwargs (and document that), but it won't show up in Fire.

    def func(self, foo, **kwargs): 
        """
        :param str foo: (required) This argument shows up
        :param str bar: (optional) This argument doesn't show up
        """

[holongate]

This is a very developer-centric view.
Contrary to function arguments (or @Annotated functions), docstrings can't be internationalized at runtime...
CLI are also for the end users.