Auto generate docstring

[DonJayamanne]

From @DonJayamanne on June 16, 2016 2:9

Copied from original issue: DonJayamanne/pythonVSCode#165

[DonJayamanne]

Suggestions for #183

[DonJayamanne]

From @diazgilberto on March 9, 2017 18:5

Is this feature working yet? If so, I can't find in VSC how to make it work.

[DonJayamanne]

From @mcepl on March 17, 2017 18:25

PyCharm has it, so when I define a new function, it gives me at least this:

[DonJayamanne]

From @changkun on May 28, 2017 5:59

looking forward for this feature..

[DonJayamanne]

From @robodair on June 11, 2017 3:22

@DonJayamanne I'd like to have a crack at this, at the moment I'm fixing unit tests on master.

Any pointers on where to start? I'm new to vscode extensions.

[DonJayamanne]

@robodair have a look at the following. My suggestion is to first get it working as a stand alone JavaScript piece of code, then try to plug into vscode using typescript.
https://packagecontrol.io/packages/AutoDocstring

[DonJayamanne]

If you need a some more info, let know and I'll try to put something together.

[DonJayamanne]

From @robodair on June 18, 2017 4:16

Javascript really doesn't seem like the tool for the job here, I feel like I'm fighting with it constantly just to extract arguments (albeit with regex) and there's no way I'm writing a python parser.

I'm thinking of doing something similar to what you've done with Jedi - so I can call out to some python code to actually work out the docstrings and just tie it into the extension more loosely, possibly adapt or generalise SublimeAutoDocstring to support both VSCode and Sublime.

Any reason that's a Bad Thing^TM?

[DonJayamanne]

From @gandhis1 on June 18, 2017 4:56

That's how the entire extension is designed. None of the syntactical components are in JS. It's all Python components.

[DonJayamanne]

From @robodair on June 18, 2017 5:23

Neat, I'll work on adding this as a completion provider then.

[DonJayamanne]

From @Marcos-Barranquero on August 29, 2017 0:25

Would be awesome.

[DonJayamanne]

From @Odame on September 2, 2017 8:21

Looking forward to this feature

[DonJayamanne]

From @edward-agarwala on September 8, 2017 19:24

@robodair, Are you still working on this?

[DonJayamanne]

From @robodair on September 9, 2017 1:15

@edward-agarwala Yes, but Uni has gone back for me and we switched to pycharm at work so I've had no time or motivation to get further quickly I'm afraid.

The python module I'm building is here: https://github.com/robodair/pydocstring

[DonJayamanne]

From @AZaugg on September 9, 2017 7:4

@DonJayamanne I had a crack at this, https://github.com/AZaugg/vscode-python-docstring did you want to take a look, if your happy i can try integrate it into your extensions.

Full disclosure, its pretty basic

[DonJayamanne]

From @robodair on September 16, 2017 15:43

Made some progress, got something that works, though there may be a few bugs in the docstring formatting.

Not sure how to go about making sure the pydocstring module is installed, ideally I'd like a warning similar to the missing pylint or formatter ones.

This is what it looks like so far:

[DonJayamanne]

From @robodair on September 16, 2017 15:51

@DonJayamanne what do you think about going further with this?

I was intending to keep maintaining pydocstring separately and have it be used the same way as pylint, but it might be easier to just take snapshots of the code and include them in the pythonVScode repo every so often?

I've also used the jediProxy to get this working instead of creating another proxy... Which might be not so good of an idea?

[DonJayamanne]

From @mcepl on September 18, 2017 8:24

@robodair Is there some template or something where I could set what strings and which format parameters are generated?

[DonJayamanne]

From @robodair on September 18, 2017 8:29

Currently no - it's only formatting google style docstrings because that's what I use.

However, the plan is to have multiple modules under pydocstring.formatters (currently there is only google) and accept a string parameter when pydocstring.generate_docstring() is called, to select which one to use, so we could provide a setting from vscode like "python.docstringFormat": "numpy"

[DonJayamanne]

From @mcepl on September 18, 2017 9:45

I would like to get the one shown in https://github.com/DonJayamanne/pythonVSCode/issues/165#issuecomment-287434730 which I believe is closest to the Pythonic standard, isn't it?

[DonJayamanne]

From @robodair on September 18, 2017 10:0

Yes that is reST style, default for Sphinx. I'll look at writing a formatter for it when I've sorted out proper integration with vscode.

It's easy to add it to pydocstring, but because I'm just piggybacking on the jediProxy right now to get it working with the extension there's not a place for me to add the preference to send it to pydocstring, without adding some sort of arbitrary object to ICommand.

I think that might feel a bit hacked-on, so I'd like @DonJayamanne or someone else who's familiar with the extension to comment on how the integration of this should work. Possibly adding something more generic than jediProxy that supports some more arbitrary payload would be useful in future (or converting jediProxy to something more generic).

[DonJayamanne]

@robodair
Apologies for the delay. I've had a look at the code and that looks great. Is there any way you could some how make use of the https://github.com/dadadel/pyment library?
That seems to support various formats.

[DonJayamanne]

From @robodair on September 19, 2017 3:16

@DonJayamanne I'll take a look - could be great for getting docstring conversion as well as formatting working quicker than I expected.

Is tacking it onto jediProxy ok or would it be better to work on a more elegant solution?

[DonJayamanne]

@robodair I'd suggest executing it in a separate python process and capturing the output in stdout (this way the new python process is shortlived and the functionality is self contained).
Let me know if you need any help in setting this up. Have a look at how the formatting and other python files are launched from nodejs in the extension.

And thanks for looking into this.

[DonJayamanne]

From @robodair on September 19, 2017 3:21

@DonJayamanne so set up a separate proxy?
Can do - Help would be appreciated because I haven't dealt with that much, but I have read through it and should be able to hack through it without help, might just take a bit longer.

[DonJayamanne]

@robodair You might also want to have a look at https://github.com/KristoforMaynard/SublimeAutoDocstring.
Personally I prefer using the AST parser as opposed to string (regex) parsing.
Or try using Jedi to get the defintion of a function and then use those details to build the documentation.

Can do - Help would be appreciated because I haven't dealt

For now, just tack onto the jedi proxy, this way you can focus on the python code.

[DonJayamanne]

From @robodair on September 19, 2017 3:30

@DonJayamanne the reason I avoided AST is that I wanted it to be able to generate python3 docstrings using python2 - Seemed easier to do with regex, which I modified from SublimeAutoDocstring.
I was hoping to avoid external dependencies but perhaps you're right and I should use jedi instead.

[DonJayamanne]

From @robodair on September 19, 2017 3:58

I was just looking at pyment - it's GPL v3, so I don't think I can use it from pydocstring and pythonVSCode because they're MIT.

[DonJayamanne]

From @robodair on September 19, 2017 5:32

I've modified jediproxy to allow a formatter to be specified in settings, there's still an exception thrown if an invalid formatter is specified, and there's no prompt about installing pydocstring.

[DonJayamanne]

I was hoping to avoid external dependencies but perhaps you're right and I should use jedi instead.

Are we using Jedi. Personally I still prefer to use some form of AST?

[DonJayamanne]

From @robodair on September 19, 2017 7:38

Currently I'm using neither - ast on python 2 won't handle python3 code and vice versa. I suppose I could just assume that the version of python used is the one that the code is for, but then it's not really compatible with both. I figured regex works well enough for the task.

[DonJayamanne]

From @mcepl on September 19, 2017 8:0

I wonder whether davidhalter/jedi#630 would be relevant discussion here.

[DonJayamanne]

From @robodair on September 19, 2017 8:16

@mcepl Intriguing.

Meanwhile I've created basic formatters for reST and numpy styles so you should be able to get the style you want.
robodair/pydocstring@ac3de4a

[DonJayamanne]

From @robodair on September 19, 2017 11:12

Parso looks like it can do the job - but for now so can regex, and I've already written the regex.

Unless there's something that must be done with a parser right now there's no reason it can't be swapped out later, if necessary.

As it stands I think the only thing that would make this not useful right now is the lack of messages/errors when pydocstring is not available, which is more to do with changes to the extension which I'm less familiar with but doesn't seem hard to add.

[DonJayamanne]

Duplicate of #62