support numpydoc

[nbara]

Hi, thanks for writing this extension!

It would be nice if one could choose a different docstyle. For instance I'm using this in most of my projects:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

[AZaugg]

Hey @nbara just committed and published the extension to support NumPy types. Let me know how it goes. Just set it in your user preferences:

"pydocs.style": "numpy"

[nbara]

Thanks for the quick update @AZaugg.

The Numpy option works but it doesn't look quite correct IMO.

For instance, for simple test(X, Y) function, I would get :

def test(X, Y):
    """
    docstring here

    Parameters
    ----------
        X:
        Y:
    """
    X + Y = Z
    return Z

Whereas it should look like this :

def test(X, Y):
    """Set docstring here.

    More doc (optional, note the empty line above and below).

    Parameters
    ----------
    X:
    Y:

    Returns
    -------
    Z:
    """
    X + Y = Z
    return Z

There are several issues:

• The docstring should comme right after the triple quotes (no newline), and be followed by a dot
• X: and Y: are over-indented (they should have the same indent as Parameters
• I assume the extension doesn't parse the function return Z, but it would be useful if by default the extension would add a Returns line by default (I would think the majority of functions have at least one output).

What do you think?

[nbara]

PS: are you aware of this package ? https://github.com/robodair/pydocstring

[AZaugg]

Ill try fix it tonight.

Yep I am aware of that project, it was brought up in: https://github.com/DonJayamanne/pythonVSCode/issues/165

Its not yet complete when I started this, and was wanting something to use ASAP, so created this extension, as a stop gap.

[AZaugg]

OK, format should look better now. You are correct, I haven't done the forward parsing for returns type just yet. Ill jump onto it once I get some spare time.

[nbara]

It looks better but it messes up when function definitions span multiple lines.

Also, it doesn't work well when passing default argument values in the function definition, such as function(X=0, y=None)