Error when inserting docstring; inserting docstring kills any existing docstring

[sonictk]

Hi:

I just installed the elisp package from MELPA, and tried using it with my Python code. I keep getting the following error message when attempting to insert a new docstring into my code, and additionally, it always kills any existing docstring inside it, instead of updating it.

Suspicious state from syntax checker python-pycompile: Checker python-pycompile returned non-zero exit code 1, but no errors from output: Sorry: IndentationError: ('unexpected indent', ('/tmp/flycheck15795ZS0/app_utils.py', 84, 9, '         callback = mari.utils.connec()\n')) Checker definition probably flawed.

Is there anything I can do to resolve this?

Thanks!

[naiquevin]

Hi,

Can you check if your code has indentation issues? The error you are getting suggests that and it's perhaps related to flycheck.

Can you confirm by trying sphinx-doc in another small python file with just 1 or 2 functions?

[vindarel]

Hi !
I noticed the following:

def foo:
    """
    mydoc
    """

here mydoc will be deleted, I need a newline after the first triple quotes:

def foo:
    """

    mydoc
    """

[vindarel]

those two tests illustrate the pb (they need s.el for s-contains-p):

(ert-deftest sphinx-doc-test-full-notok ()
  (let ((start "
def foo(arg1):
\"\"\"
first line

\"\"\"
pass
")
        (end "
def foo(arg1):
\"\"\"
first line

:param arg1:

\"\"\""))
    (should (s-contains-p "first line"
                          (with-temp-buffer
                            (insert start)
                            (sphinx-doc-mode)
                            (sphinx-doc)
                            (buffer-string))))))

(ert-deftest sphinx-doc-test-full-ok ()
  (let ((start "
def foo(arg1):
\"\"\"

first line

\"\"\"
pass
")
        (end "
def foo(arg1):
\"\"\"

first line

:param arg1:

\"\"\"
pass
"))
    (should (s-contains-p "first line"
                          (with-temp-buffer
                            (insert start)
                            (sphinx-doc-mode)
                            (sphinx-doc)
                            (buffer-string))))))

[humitos]

I found different situations:

1. with this scenario, it works

def myfunction(a, b, c):
    """One-line description here.

    Long description here.

    :param a: a
    :param b: b
    :param c: c
    :returns: None
    :rtype: None

    """
    print('hello')

adding a new attribute d to my function and pressing C-c M-d at the function level, its autocomplete the docstring with the d attribute.

2. this example does not work

def myfunction(a, b, c):
    """
    One-line description here.

    Long description here.

    :param a: a
    :param b: b
    :param c: c
    :returns: None
    :rtype: None

    """
    print('hello')

adding a new attribute d to my function and pressing C-c M-d at the function level, its autocomplete the docstring with the d attribute but removes the initial line of my dosctring and the result is:

def myfunction(a, b, c, d):
    """

    Long description here.

    :param a: a
    :param b: b
    :param c: c
    :param d: 
    :returns: None
    :rtype: None

    """
    print('hello')

So, it seems that it has an issue when the initial docstring is not at the same level than """ but in the next line.

[naiquevin]

Thanks for reporting this. I will take a look at it. PRs are also welcome. However, I would like this mode to support only the most common use case. It involves string parsing which quickly gets complicated and often expensive with regex so no point in aiming for all possible ways. Personally I start docstrings immediately after """" on the same line. If some other format is considered idiomatic by the python community, please point me to it. In that case, I don't mind moving to that standard.

[humitos]

I understand. PEP 257 (https://www.python.org/dev/peps/pep-0257/) doesn't say too much about the this particular case. Here it just mentions this situation as something valid. That's all: https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation

I'm not good at elisp and I have no time at the moment to jump and learn about this to propose a PR, sorry. I just wanted to add more context to this since I was bitten by it also. Thanks for your comment.

[vindarel]

string parsing which quickly gets complicated and often expensive with regex so no point in aiming for all possible ways.

I agree. Maybe we can pre-process the docstring to make it compliant to the parser. Like, if the """ are followed by characters, we put them on a newline and then the parser does its job, when it is assured to have triple quotes followed by a newline.