vague unpack parsing errors parsing google docstrings.

[Granitosaurus]

I'm using google docstrings format for my docstrings and I'm often getting:

annotation, description = exception_line.split(": ")
ValueError: not enough values to unpack (expected 2, got 1)

It's really difficult to debug when the traceback only says which file is causing the error. Would be nice to include at least an aproximate where the fault actually is.

[pawamoy]

Is it the complete traceback? Did you run mkdocs serve with -v option? Could you paste the output here? And link to your repo so I can try it myself to see how I can improve the message :) ?

[Granitosaurus]

@pawamoy the -v flag doesn't provide any more info and I'm afraid my repo is private. That being said the issue is caused by lack trailing spaces after docstring annotations:

"""
Raises:<space><space>
    ConnectionError: if there's no internet connection
"""

There has to be double space after annotation or mkdocstrings will have an error as described in original post.

[pawamoy]

I don't think this is what is causing the issue. The traceback says "not enough values to unpack (expected 2, got 1)", so it probably means that an item in a dosctring section is not properly indented, or doesn't have a colon :. Besides, the code is tested without double-spaces after a section title, and it is working fine.

[pawamoy]

This will add a warning to the output with the path to the object's docstring causing the issue (pytkdocs code):

         for exception_line in block:
-            annotation, description = exception_line.split(": ")
-            exceptions.append(AnnotatedObject(annotation, description.lstrip(" ")))
+            try:
+                annotation, description = exception_line.split(": ")
+            except ValueError:
+                self.parsing_errors.append(f"{self.path}: Failed to get 'exception: description' pair from '{exception_line}'")
+            else:
+                exceptions.append(AnnotatedObject(annotation, description.lstrip(" ")))

Expect a bugfix release of pytkdocs soon 🙂

Thanks for the report!

[pawamoy]

Ah, and for things related to docstring parsing, could you open the issue on pytkdocs instead next time? Thanks 🙂

[Granitosaurus]

Thanks for the patch! Sorry for opening up the issue in the wrong project, wasn't aware the parsing is done in pytkdocs.

I found my issue. It was underindenting followup lines:

Returns:
    foo: this returns foo
    or something else
# should be
Returns:
    foo: this returns foo
        or something else