:key: parameter documentation doesn't correctly display in help signature

[ntjess]

Consider the following application:

import fire

def test(a, b, **test):
  """
  Returns the operation specified on a and b.
  
  :param a: The first parameter
  :param b: The second parameter
  
  :key operation: What to do with these parameters
  """
  op = test.get('operation', sum)
  return op([a,b])
  
fire.Fire(test)

Since :key: is recognized as sphinx documentation for keyword arguments, I would expect Fire to show it similar to :param: docstrings. However, the printout ends up looking like this:

POSITIONAL ARGUMENTS
    A
        The first parameter
    B
        The second parameter

        :key operation: What to do with these parameters

Where the key is not displayed as a separate argument. Compare that to the PyCharm help signature:

[dbieber]

Thanks for reporting this.
We would like to support this but don't yet.

The relevant source file is fire/docstrings.py.

[amy-lei]

I would love to work on this if no one started yet! 😃

[amy-lei]

I started looking into this and wanted to get input before proceeding.

Following OP's example, is the desired output something like this, where it is its own section:

KEYWORD ARGUMENTS
    operation
        What to do with these parameters

or, should it be listed under flags:

FLAGS
    --operation=OPERATION

[dbieber]

I think it should go under flags.

e.g. something like this:

FLAGS
    --arg=ARG

The following flags are also accepted.
    --key
      Description of the `key` kwarg from the docstring

Additional undocumented flags may also be accepted.

[dbieber]

Done in #275