documentation of commands/arguments

[sdementen]

I have some questions/comments on the "user friendliness" of fire.

With the following script fire_test.py

import fire


class Example(object):
    """this is an example module with some functions"""

    def hello(self, name, message="hello", count=3):
        """Says count times the message to the specified name

        :param name (str): the name of the person
        :param message (str): the message to say to the person
        :param count (int): the number of times the message should be repeated
        :return: the expected result
        """
        return 'Hello {name}!'.format(name=name) * count


if __name__ == '__main__':
    fire.Fire(Example)

the call to python fire_test.py hello returns

Fire trace:
1. Initial component
2. Instantiated class "Example" (fire_test.py:4)
3. Accessed property "hello" (fire_test.py:7)
4. ('The function received no value for the required argument:', 'name')

Type:        method
String form: <bound method Example.hello of <__main__.Example object at 0x0000000002A2F9E8>>
File:        c:\users\gfj138\pycharmprojects\piecash\piecash\scripts\fire_test.py
Line:        7
Docstring:   Says count times the message to the specified name.

:param name (str): the name of the person
:param message (str): the message to say to the person
:param count (int): the number of times the message should be repeated
:return: the expected result

Usage:       fire_test.py hello NAME [MESSAGE] [COUNT]
             fire_test.py hello --name NAME [--message MESSAGE] [--count COUNT]

where:

• the fire trace looks more like a "debugging feature" than a "user feedback"
• the same for the Type/String form/File/Line information
• the docstring is displayed as such which make it not user friendly
• the default values of the optional arguments are not visible

Is there some better way to document the commands and their arguments I may be missing ?
Any good practice re documentation ?

[dbieber]

I agree about your points 1, 2, and 4. These are areas we should improve.

I'm not sure I understand what you're saying in point 3 about the docstring. Is it the way the docstring is displayed that you think could be improved, or do you think showing the docstring at all is the problem?

There was some discussion around improving these areas in #26, but it isn't currently being actively worked on.

[sdementen]

yes, for 3 it is indeed about parsing the docstring to avoiding showing the :param ...: part as such

:param name (str): the name of the person
:param message (str): the message to say to the person
:param count (int): the number of times the message should be repeated
:return: the expected result

I read #26 and I see most of the points where already being discussed...

[dbieber]

We've addressed all four of the points you raised!
The new release comes out tomorrow (July 26).

(Edit: Actually we've only addressed 1, 2, and 3 so far. We still don't show defaults, as david-macleod points out. #184 tracks this.)

[david-macleod]

After installing version 0.2.1 I still cannot see the default values of default arguments (point 4 above). Am I doing something incorrect?

import fire

def function(arg1, arg2=10):
    '''
    My function

    :param arg1: argument 1
    :param arg2: argument 2
    '''

    return arg1 * arg2

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

Calling python.py tmp.py function --help returns

NAME
    tmp.py function - My function

SYNOPSIS
    tmp.py function ARG1 <flags>

DESCRIPTION
    My function

POSITIONAL ARGUMENTS
    ARG1
        argument 1

FLAGS
    --arg2=ARG2
        argument 2

NOTES
    You can also use flags syntax for POSITIONAL ARGUMENTS

I was hoping to see arg2=10 as default value shown somewhere in the output.

Thank you

[dbieber]

Oh, sorry I misspoke. No, the defaults are not visible in help screens today. Let's open a new issue to track that: #184