The napoleon docstring preprocessor has been ported from sphinx. It's a great and complete piece of code. It has only one drawback, and that's the fact that it messes up with the line numbers of docstring fields. It is a completely normal side effect since the code operates as a string transformer before parsing it with docutils.
Even for the simplest example, some offset will be of 1, and this is probably best to accept otherwise we have to look at re-implementing the whole google and numpy parsing. And this is not a viable option for the moment. So let's say an offset of 1 is acceptable. But still I wonder if we could ensure at any time len(original_docsstring.splitlines()) == len(transformed_docstring.splitlines()).
Anyway here goes a few examples of cases that could be improved:
Example Function
Raises:
InvalidDimensionsError: With description
Is transformed into :
Example Function
:raises InvalidDimensionsError: With description
But it would best if that was
Example Function
:raises InvalidDimensionsError: With description
And
Example Function
Raises:
InvalidDimensionsError:
With description
Is transformed into the same :
Example Function
:raises InvalidDimensionsError: With description
But it would best if that was
Example Function
:raises InvalidDimensionsError:
With description
So now look at example where the line number diffs are greater
Example Function
Raises:
RuntimeError:
A setting wasn't specified, or was invalid.
ValueError:
Something something value error.
:py:class:`AttributeError`
errors for missing attributes.
~InvalidDimensionsError
If the dimensions couldn't be parsed.
`InvalidArgumentsError`
If the arguments are invalid.
:exc:`~ValueError`
If the arguments are wrong.
Is transformed into :
Example Function
:raises RuntimeError: A setting wasn't specified, or was invalid.
:raises ValueError: Something something value error.
:raises AttributeError: errors for missing attributes.
:raises ~InvalidDimensionsError: If the dimensions couldn't be parsed.
:raises InvalidArgumentsError: If the arguments are invalid.
:raises ~ValueError: If the arguments are wrong.
But it would best if that was
Example Function
:raises RuntimeError:
A setting wasn't specified, or was invalid.
:raises ValueError:
Something something value error.
:raises AttributeError:
errors for missing attributes.
:raises ~InvalidDimensionsError:
If the dimensions couldn't be parsed.
:raises InvalidArgumentsError:
If the arguments are invalid.
:raises ~ValueError:
If the arguments are wrong.
Another interesting example is the return clause that is translated to two fields.
Example Function
Returns:
:class:`numpy.ndarray`: A :math:`n \\times 2` array containing
a bunch of math items
Is transformed into :
Example Function
:returns: A :math:`n \\times 2` array containing
a bunch of math items
:returntype: :class:`numpy.ndarray`
But it would best if that was
Example Function
:returntype: :class:`numpy.ndarray`
:returns: A :math:`n \\times 2` array containing
a bunch of math items
The napoleon docstring preprocessor has been ported from sphinx. It's a great and complete piece of code. It has only one drawback, and that's the fact that it messes up with the line numbers of docstring fields. It is a completely normal side effect since the code operates as a string transformer before parsing it with docutils.
Even for the simplest example, some offset will be of 1, and this is probably best to accept otherwise we have to look at re-implementing the whole google and numpy parsing. And this is not a viable option for the moment. So let's say an offset of 1 is acceptable. But still I wonder if we could ensure at any time
len(original_docsstring.splitlines()) == len(transformed_docstring.splitlines()).Anyway here goes a few examples of cases that could be improved:
Is transformed into :
But it would best if that was
And
Is transformed into the same :
But it would best if that was
So now look at example where the line number diffs are greater
Is transformed into :
But it would best if that was
Another interesting example is the return clause that is translated to two fields.
Is transformed into :
But it would best if that was