Feature/docstring parsing

[sanga]

A few tests and changes to get them working on top of @joshlk 's PR. Apologies if I've trampled on any toes here, would just really like to get that work in (it's currently what's stopping me from switching to argh)

[coveralls]

Coverage decreased (-4.9%) to 88.475% when pulling 6bf3fe7fc35a3cbe261d12f4fc4321db4aff68cf on sanga:feature/docstring_parsing into dcd3253f2994400a6a58a700c118c53765bc50a4 on neithere:master.

[coveralls]

Coverage decreased (-4.9%) to 88.475% when pulling 6bf3fe7fc35a3cbe261d12f4fc4321db4aff68cf on sanga:feature/docstring_parsing into dcd3253f2994400a6a58a700c118c53765bc50a4 on neithere:master.

[joshlk]

@sanga thanks! Im quite busy at the moment so very grateful for your work

[sanga]

One thing came to mind about this. It'd be nicer if we dropped the sphinx-style param definitions from the function docstring otherwise you end up with this situation:

Takes a directory as a param and returns the following object to stdout:
        {
            context: [context.json],
            request: [request.json]
        }
    :param directory: the directory containing the context and request json files

positional arguments:
  directory   the directory containing the context and request json files

optional arguments:
  -h, --help  show this help message and exit

note the superfluous ":param directory: the directory containing the context and request json files" is the function description.

I could drop that just by changing the __doc__ of a function annotated with @parse_docstring but that feels a little ugly (we're actually modifying the function in that case so calling for example func? in ipython won't have param info in the docstring anymore. Would that be acceptable? Or how to fix it otherwise? Add another attribute to the annotated function that would get picked up later by argh?

[joshlk]

The way im currently doing it is modifying the parser description like so:

def parse_description(func, format='sphinx'):
    """
    Return the description using the docstring by parsing the functions docstring

    :param func: Function to obtain the description from
    :param format: Which docstring format
    :return: String of the description
    """

    if format not in ['sphinx']:
        raise NotImplementedError("sphinx is currently only supported")

    return parse_sphinx_doc(func.__doc__).get('description', None)

parser.description = parse_description(star_selection.run)

But im not sure how to make the flow pretty

[sanga]

Yeah I pretty much had the same issue as you. I see where it should go but couldn't figure out in the time available where that hooking should happen. In any case I guess I won't continue with this as after reading the docs I noticed that py3k style type hints will get picked up as arg docs. That's much more convenient for me.