search

heavenshell / vim-pydocstring

Generate Python docstring to your Python source code.
BSD 3-Clause "New" or "Revised" License
337 stars 53 forks source link

numpy style docstring? #2

Closed nye17 closed 10 years ago

nye17 commented 10 years ago

Is it trivial to add support for numpy style docstring like

Parameters
----------------
x : float
    x is this stuff.

Returns
-----------
y : float
    y is that stuff.
heavenshell commented 10 years ago

Thank you for request.

Unfortunately, I'm not familiar with Numpy. But I add feature_numpy branch. Note: this is experimental.

Could you try this?

Change template/pydocstring/multi.txt like following.

"""{{_header_}}

{{_arg_}} :{{_lf_}}{{_indent_}}    {{_arg_}} is
"""

And then type :Pydocstring

def foo(arg1, arg2):
    pass

will generate docstring like following.

def foo(arg1, arg2):
    """foo

    arg1:
        arg1 is
    arg2:
        arg2 is
    """
    pass

Sorry, pydocstring.vim can't generate variable type and return value. You should add them manually.

nye17 commented 10 years ago

Hi!

Thanks! That's close!

variable type and return value are hard, but is it possible to simply add the "Parameters" and "Returns" strings with the right level of indentation?

heavenshell commented 10 years ago

Hi,

So, you meant like following?

def foo(arg1, arg2):
  """foo

    arg1:
        arg1 is Parameters
    arg2:
        arg2 is Parameters

    Returns 
    """
  pass
nye17 commented 10 years ago

something like that --- basically to generate lines with fixed strings with the right indentation.

def foo(x) :
    Parameters
    ----------------
    x : float
        x is this stuff.

    Returns
    -----------
heavenshell commented 10 years ago

Hi, I updated feature_numpy.

Set following template to multi.txt

"""
{{_indent_}}Parameters
{{_indent_}}----------------

{{_arg_}} : vartype{{_lf_}}{{_indent_}}    {{_arg_}} is

{{_indent_}}Returns
{{_indent_}}----------------

"""

Results are following.

def foo(x):
  """
    Parameters
    ----------------

    x : vartype
        x is

    Returns
    ----------------

    """
  pass

Thanks.

nye17 commented 10 years ago

Hey!

That’s pretty much what I want, except for a minor problem that is most likely caused by vim config on my end.

The indentation is sorta screwed up in my MacVim, where eight spaces show up instead of four. Any ideas?

Thanks!

On Dec 6, 2013, at 9:52 PM, heavenshell notifications@github.com wrote:

Hi, I updated feature_numpy.

Set following template to multi.txt

""" {{indent}}Parameters {{indent}}----------------

{{arg}} : vartype{{lf}}{{indent}} {{arg}} is

{{indent}}Returns {{indent}}----------------

""" Results are following

def foo(x): """ Parameters

x : vartype
    x is

Returns
----------------

"""
pass

— Reply to this email directly or view it on GitHub.

heavenshell commented 10 years ago

fmm, interesting.

Could you confirm your tab setting? My .vimrc tab setting is following and works fine for me.

autocmd FileType python setlocal tabstop=4 shiftwidth=4 softtabstop=4 expandtab
nye17 commented 10 years ago

I pretty much have the same setting as yours, except for the lack of softtabstop which seems irrelevant.

I tried the macro on this test script

def foo(a) : pass

if True : def foo(b) : pass if True : def foo(c) : pass

and the indentation only works for foo(b), but overshoots for the other functions.

On Dec 7, 2013, at 12:56 AM, heavenshell notifications@github.com wrote:

fmm, interesting.

Could you confirm your tab setting? My .vimrc tab setting is following and works fine for me.

autocmd FileType python setlocal tabstop=4 shiftwidth=4 softtabstop=4 expandtab — Reply to this email directly or view it on GitHub.

heavenshell commented 10 years ago

fmm, works fine in my MacVim...

def foo(a):
    """
    Parameters
    ----------------

    a : vartype
        a is

    Returns
    ----------------

    """
    pass

if True:
    def bar(b):
        """
        Parameters
        ----------------

        b : vartype
            b is

        Returns
        ----------------

        """
        pass
    if True :
        def baz(c):
            """
            Parameters
            ----------------

            c : vartype
                c is

            Returns
            ----------------

            """
            pass

Could you show results of following command? $ vim sample.py :set tabstop :set shiftwidth :set softtabstop

And, could you add debug print to autoload/pydocstring.vim and show me the result of :message?

function! pydocstring#insert()
  silent! execute 'normal! 0'
  let line = getline('.')
  let indent = matchstr(line, '^\(\s*\)')
  echomsg 'indent:' . len(indent) # <- add this
nye17 commented 10 years ago

Hi,

I am a bit confused about the debugging message stuff, but the new finding is that,

I have set tabstop to be 4 in vimrc, and it indeed shows up 4 if I open up some non-python files, but when I open a python file the tabstop is then changed to 8. I’m not sure how to track down which plugin did this, but even when I remove all my plugins in my bundle directory the wonky behavior still happens…..

On Dec 7, 2013, at 2:12 AM, heavenshell notifications@github.com wrote:

function! pydocstring#insert() silent! execute 'normal! 0' let line = getline('.') let indent = matchstr(line, '^(\s*)') echomsg 'indent:' . len(indent)

heavenshell commented 10 years ago

Hi,

I am a bit confused about the debugging message stuff, but the new finding is that,

Sorry about confusing you:-(

OK, then try :verbose set tabstop. This command will track down tabstop set.

nye17 commented 10 years ago

okay, apparently it was modified by the python.vim plugin that ships with my MacVim (version: 7.4-72) package. I’ve no idea why it changes my tabstop from 4 to 8 though….

On Dec 7, 2013, at 3:52 AM, heavenshell notifications@github.com wrote:

Hi,

I am a bit confused about the debugging message stuff, but the new finding is that,

Sorry about confusing you:-(

OK, then try :verbose set tabstop. This command will track down tabstop set.

— Reply to this email directly or view it on GitHub.

nye17 commented 10 years ago

this is what appears in my /usr/local/Cellar/macvim/7.4-72/MacVim.app/Contents/Resources/vim/runtime/ftplugin/python.vim file,

" As suggested by PEP8. setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8

this is brutal… ;-(

On Dec 7, 2013, at 3:52 AM, heavenshell notifications@github.com wrote:

Hi,

I am a bit confused about the debugging message stuff, but the new finding is that,

Sorry about confusing you:-(

OK, then try :verbose set tabstop. This command will track down tabstop set.

— Reply to this email directly or view it on GitHub.

nye17 commented 10 years ago

according to this, apparently I should stick to tabstop=8 as PEP8 advertised for it….

is it possible to make pydocstring tabstop-agnostic?

On Dec 7, 2013, at 3:57 AM, Ying Zu zuying@gmail.com wrote:

this is what appears in my /usr/local/Cellar/macvim/7.4-72/MacVim.app/Contents/Resources/vim/runtime/ftplugin/python.vim file,

" As suggested by PEP8. setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8

this is brutal… ;-(

On Dec 7, 2013, at 3:52 AM, heavenshell notifications@github.com wrote:

Hi,

I am a bit confused about the debugging message stuff, but the new finding is that,

Sorry about confusing you:-(

OK, then try :verbose set tabstop. This command will track down tabstop set.

— Reply to this email directly or view it on GitHub.

nye17 commented 10 years ago

forgot the link

http://stackoverflow.com/questions/19718837/macvim-line-continuation-in-python-creates-unnecessary-tab

On Dec 7, 2013, at 4:00 AM, Ying Zu zuying@gmail.com wrote:

according to this, apparently I should stick to tabstop=8 as PEP8 advertised for it….

is it possible to make pydocstring tabstop-agnostic?

On Dec 7, 2013, at 3:57 AM, Ying Zu zuying@gmail.com wrote:

this is what appears in my /usr/local/Cellar/macvim/7.4-72/MacVim.app/Contents/Resources/vim/runtime/ftplugin/python.vim file,

" As suggested by PEP8. setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8

this is brutal… ;-(

On Dec 7, 2013, at 3:52 AM, heavenshell notifications@github.com wrote:

Hi,

I am a bit confused about the debugging message stuff, but the new finding is that,

Sorry about confusing you:-(

OK, then try :verbose set tabstop. This command will track down tabstop set.

— Reply to this email directly or view it on GitHub.

heavenshell commented 10 years ago

Nice catch!

OK, how about put follwing vim setting to ~/.vim/after/ftplugin/python.vim

autocmd FileType python setlocal tabstop=4 shiftwidth=4 softtabstop=4 expandtab
nye17 commented 10 years ago

Added the after/ftplugin/python.vim file with the autocmd line, and :scriptnames reveals that the file was indeed sourced after the system-wide python.vim was sourced. However, still, verbose set tabstop still says it is 8 and was last modified by the aforementioned python.vim file. It seems that the added after-command wasn't correctly parsed....very confusing

heavenshell commented 10 years ago

Oh, sorry it's my fault.

Try following vim setting to ~/.vim/after/ftplugin/python.vim

setlocal tabstop=4 shiftwidth=4 softtabstop=4 expandtab

tabstop 8 reproduce indent problem. I have to consider about this issue.

nye17 commented 10 years ago

okay, no the indentation works correctly.

However, for functions defined as

def foo(a) :

notice the extra space after the second parenthesis. The script failed to identify “a" as the argument but "a)”.

BTW: I like to leave one extra space because some color scheme requires a separation between colon and keywords for highlighting.

On Dec 7, 2013, at 5:10 AM, heavenshell notifications@github.com wrote:

Oh, sorry it's my fault.

Try following set to ~/.vim/after/ftplugin/python.vim

setlocal tabstop=4 shiftwidth=4 softtabstop=4 expandtab tabstop 8 reproduce indent problem. I have to consider about this issue.

— Reply to this email directly or view it on GitHub.

heavenshell commented 10 years ago

Thanks, good to hear that! I'll look into tabstop indent problem and after issue will solved, I'll merge to master. Please wait.

notice the extra space after the second parenthesis. The script failed to identify “a" as the argument but "a)”.

Ah, I reproduced the problem, but this problem is not related to Numpy style docstring issue. I'll create new issue.

Thank you for improving pydocstring.vim better.