Bullet point lists of arguments break if multiline

[peterjc]

Example, call this test_bullets.py,

"""Silly mathematical example."""

import math

def euclidean_distance(point_a, point_b):
    """Return the Euclidean distance between points A and B.

    Arguments:
     - point_a - point in space as a list, tuple or array.
     - point_b - point in space as a list, tuple or array.
       This should be the same length as point_a.

    Example:

    >>> euclidean_distance((0, 0), (3, 4))
    5.0

    """
    if len(point_a) != len(point_b):
        raise ValueError("Points A and B must have the same length (dimensionality).")
    sum_of_squares = sum((a - b)**2 for (a, b) in zip(point_a, point_b))
    return math.sqrt(sum_of_squares)

if __name__ == "__main__":
    alpha = (1, 1, 1)
    beta =  (1, 4, 5)
    print("Example, distance from %r to %r is %r" %
          (alpha, beta, euclidean_distance(alpha, beta)))

Actual output:

$ pyment -o reST test_bullets.py && more test_bullets.py.patch
9 10
# Patch generated by Pyment v0.3.2

--- a/test_bullets.py
+++ b/test_bullets.py
@@ -3,18 +3,15 @@
 import math

 def euclidean_distance(point_a, point_b):
-    """Return the Euclidean distance between points A and B.
+    """

-    Arguments:
-     - point_a - point in space as a list, tuple or array.
-     - point_b - point in space as a list, tuple or array.
-       This should be the same length as point_a.
-
-    Example:
+    :param point_a: point in space as a list
+    :param point_b: point in space as a list
+    :param This: should be the same length as point_a
+    :param Example: 

     >>> euclidean_distance((0, 0), (3, 4))
     5.0
-
     """
     if len(point_a) != len(point_b):
         raise ValueError("Points A and B must have the same length (dimensionality).")

Or:

"""Silly mathematical example."""

import math

def euclidean_distance(point_a, point_b):
    """

    :param point_a: point in space as a list
    :param point_b: point in space as a list
    :param This: should be the same length as point_a
    :param Example: 

    >>> euclidean_distance((0, 0), (3, 4))
    5.0
    """
    if len(point_a) != len(point_b):
        raise ValueError("Points A and B must have the same length (dimensionality).")
    sum_of_squares = sum((a - b)**2 for (a, b) in zip(point_a, point_b))
    return math.sqrt(sum_of_squares)

if __name__ == "__main__":
    alpha = (1, 1, 1)
    beta =  (1, 4, 5)
    print("Example, distance from %r to %r is %r" %
          (alpha, beta, euclidean_distance(alpha, beta)))

Note the problem line :param This: should be the same length as point_a created from the second line of the bullet point for argument point_b.

Note also the problem line :param Example:

Note also that the periods (full stops) have been removed.

Note also the one-line summary Return the Euclidean distance between points A and B. was removed.

Expected output:

There is some flexibility but the continuation line must be indented, this is a valid reStructuredText docstring:

"""Silly mathematical example."""

import math

def euclidean_distance(point_a, point_b):
    """Return the Euclidean distance between points A and B.

    :param point_a: point in space as a list
    :param point_b: point in space as a list
      This should be the same length as point_a

    Example: 

    >>> euclidean_distance((0, 0), (3, 4))
    5.0
    """
    if len(point_a) != len(point_b):
        raise ValueError("Points A and B must have the same length (dimensionality).")
    sum_of_squares = sum((a - b)**2 for (a, b) in zip(point_a, point_b))
    return math.sqrt(sum_of_squares)

if __name__ == "__main__":
    alpha = (1, 1, 1)
    beta =  (1, 4, 5)
    print("Example, distance from %r to %r is %r" %
          (alpha, beta, euclidean_distance(alpha, beta)))

[dadadel]

Hi @peterjc, Thanks for reporting this issue. I'll try to considere this. Concerning Example, Pyment doesn't know that keyword so it considered it as a parameter.

[Sup3rGeo]

Maybe pyment could consider all the sections sphinx also does?

https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

Docstring Sections All of the following section headers are supported:

Args (alias of Parameters) Arguments (alias of Parameters) Attention Attributes Caution Danger Error Example Examples Hint Important Keyword Args (alias of Keyword Arguments) Keyword Arguments Methods Note Notes Other Parameters Parameters Return (alias of Returns) Returns Raises References See Also Tip Todo Warning Warnings (alias of Warning) Warns Yield (alias of Yields) Yields

@dadadel how hard would be to implement this? Could you give some pointers where to change this in the code?