Skip to content

Make ArrowStyle docstrings numpydoc compatible #8343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 24, 2017
Merged

Make ArrowStyle docstrings numpydoc compatible #8343

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bd1e4d7
Make ArrowStyle docstrings numpydoc compatible
patniharshit Mar 19, 2017
0009035
add default values and remove mixture of tabs and spaces
patniharshit Mar 20, 2017
b8ae472
add 0 with decimals
patniharshit Mar 20, 2017
2a31cca
change indentation of parameter description
patniharshit Mar 21, 2017
389d85b
update docstring to reflect the call signature
patniharshit Mar 23, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
add default values and remove mixture of tabs and spaces
  • Loading branch information
@patniharshit
patniharshit committed Mar 20, 2017
commit 0009035c35644481b0fa43aa04537bd154e893fa
163 changes: 88 additions & 75 deletions lib/matplotlib/patches.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3407,7 +3407,8 @@ def transmute(self, path, mutation_size, linewidth):
return _path, _fillable

class Curve(_Curve):
"""A simple curve without any arrow head.
"""
A simple curve without any arrow head.
"""

def __init__(self):
Expand All @@ -3417,18 +3418,19 @@ def __init__(self):
_style_list["-"] = Curve

class CurveA(_Curve):
"""An arrow with a head at its begin point.
"""
An arrow with a head at its begin point.
"""

def __init__(self, head_length=.4, head_width=.2):
"""
Parameters
----------
head_length : float, optional
head_length : float, optional, default : .4
Length of the arrow head
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

4-space indent, please.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for that, I should not have mixed tabs and spaces.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be indented only 4 more spaces from the previous line.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here only or everywhere?

Copy link
Member

@phobson phobson Mar 21, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

everywhere. Should like:

...
            Parameters
            ----------
            head_length : float, optional, default : 0.4
                Length of the arrow head
...


head_width : float, optional
Width of the arrow head
head_width : float, optional, default : .2
Width of the arrow head
"""

super(ArrowStyle.CurveA, self).__init__(
Expand All @@ -3438,18 +3440,19 @@ def __init__(self, head_length=.4, head_width=.2):
_style_list["<-"] = CurveA

class CurveB(_Curve):
"""An arrow with a head at its end point.
"""
An arrow with a head at its end point.
"""

def __init__(self, head_length=.4, head_width=.2):
"""
Parameters
----------
head_length : float, optional
head_length : float, optional, default : .4
Length of the arrow head

head_width : float, optional
Width of the arrow head
head_width : float, optional, default : .2
Width of the arrow head
"""

super(ArrowStyle.CurveB, self).__init__(
Expand All @@ -3459,18 +3462,19 @@ def __init__(self, head_length=.4, head_width=.2):
_style_list["->"] = CurveB

class CurveAB(_Curve):
"""An arrow with heads both at the begin and the end point.
"""
An arrow with heads both at the begin and the end point.
"""

def __init__(self, head_length=.4, head_width=.2):
"""
Parameters
----------
head_length : float, optional
head_length : float, optional, default : .4
Length of the arrow head

head_width : float, optional
Width of the arrow head
head_width : float, optional, default : .2
Width of the arrow head
"""

super(ArrowStyle.CurveAB, self).__init__(
Expand All @@ -3480,18 +3484,19 @@ def __init__(self, head_length=.4, head_width=.2):
_style_list["<->"] = CurveAB

class CurveFilledA(_Curve):
"""An arrow with filled triangle head at the begin.
"""
An arrow with filled triangle head at the begin.
"""

def __init__(self, head_length=.4, head_width=.2):
"""
Parameters
----------
head_length : float, optional
head_length : float, optional, default : .4
Length of the arrow head

head_width : float, optional
Width of the arrow head
head_width : float, optional, default : .2
Width of the arrow head
"""

super(ArrowStyle.CurveFilledA, self).__init__(
Expand All @@ -3502,18 +3507,19 @@ def __init__(self, head_length=.4, head_width=.2):
_style_list["<|-"] = CurveFilledA

class CurveFilledB(_Curve):
"""An arrow with filled triangle head at the end.
"""
An arrow with filled triangle head at the end.
"""

def __init__(self, head_length=.4, head_width=.2):
"""
Parameters
----------
head_length : float, optional
head_length : float, optional, default : .4
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @NelleV

I don't we should have two colons in the same sentence. It looks weird to me (but it's not a deal breaker). I think this should read:

headhead_length : float, optional (default is 0.4)

The other question is if these parameters are actually optional. What I mean by that is if you said head_length=None, would this still work by falling back to the default value? If not, then the parameter isn't actually, optional, just named.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional does not imply that passing None does the default; it implies that not passing it uses the default.

Copy link
Member

@phobson phobson Mar 21, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@QuLogic

You are correct. From the numpydoc spec:

If it is not necessary to specify a keyword argument, use optional:

x : int, optional
Optional keyword parameters have default values, which are displayed as part of the function signature. They can also be detailed in the description:

Description of parameter `x` (the default is -1, which implies summation
over all axes).

(though I wish the meaning of "optional" in this context was a little more precise.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should I change the way defaults are shown then?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would be my preference, but I'm not going to hold up this PR for that.

Length of the arrow head

head_width : float, optional
Width of the arrow head
head_width : float, optional, default : .2
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For all of these, the numbers need a leading zero before the decimal (e.g., ".2" -> "0.2")

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Width of the arrow head
"""

super(ArrowStyle.CurveFilledB, self).__init__(
Expand All @@ -3524,19 +3530,19 @@ def __init__(self, head_length=.4, head_width=.2):
_style_list["-|>"] = CurveFilledB

class CurveFilledAB(_Curve):
"""An arrow with filled triangle heads both at the begin and the end
point.
"""
An arrow with filled triangle heads at both ends.
"""

def __init__(self, head_length=.4, head_width=.2):
"""
Parameters
----------
head_length : float, optional
head_length : float, optional, default : .4
Length of the arrow head

head_width : float, optional
Width of the arrow head
head_width : float, optional, default : .2
Width of the arrow head
"""

super(ArrowStyle.CurveFilledAB, self).__init__(
Expand Down Expand Up @@ -3624,7 +3630,8 @@ def transmute(self, path, mutation_size, linewidth):
return p, False

class BracketAB(_Bracket):
"""An arrow with a bracket(]) at both ends.
"""
An arrow with a bracket(]) at both ends.
"""

def __init__(self,
Expand All @@ -3633,23 +3640,23 @@ def __init__(self,
"""
Parameters
----------
widthA : float, optional
Width of the bracket
widthA : float, optional, default : 1.
Width of the bracket

lengthA : float, optional
lengthA : float, optional, default : 0.2
Length of the bracket

angleA : float, optional
Angle between the bracket and the line
angleA : float, optional, default : None
Angle between the bracket and the line

widthB : float, optional
Width of the bracket
widthB : float, optional, default : 1.
Width of the bracket

lengthB : float, optional
lengthB : float, optional, default : 0.2
Length of the bracket

angleB : float, optional
Angle between the bracket and the line
angleB : float, optional, default : None
Angle between the bracket and the line
"""

super(ArrowStyle.BracketAB, self).__init__(
Expand All @@ -3660,21 +3667,22 @@ def __init__(self,
_style_list["]-["] = BracketAB

class BracketA(_Bracket):
"""An arrow with a bracket(]) at its end.
"""
An arrow with a bracket(]) at its end.
"""

def __init__(self, widthA=1., lengthA=0.2, angleA=None):
"""
Parameters
----------
widthA : float, optional
Width of the bracket
widthA : float, optional, default : 1.
Width of the bracket

lengthA : float, optional
lengthA : float, optional, default : 0.2
Length of the bracket

angleA : float, optional
Angle between the bracket and the line
angleA : float, optional, default : None
Angle between the bracket and the line
"""

super(ArrowStyle.BracketA, self).__init__(True, None,
Expand All @@ -3685,21 +3693,22 @@ def __init__(self, widthA=1., lengthA=0.2, angleA=None):
_style_list["]-"] = BracketA

class BracketB(_Bracket):
"""An arrow with a bracket([) at its end.
"""
An arrow with a bracket([) at its end.
"""

def __init__(self, widthB=1., lengthB=0.2, angleB=None):
"""
Parameters
----------
widthB : float, optional
Width of the bracket
widthB : float, optional, default : 1.
Width of the bracket

lengthB : float, optional
lengthB : float, optional, default : 0.2
Length of the bracket

angleB : float, optional
Angle between the bracket and the line
angleB : float, optional, default : None
Angle between the bracket and the line
"""

super(ArrowStyle.BracketB, self).__init__(None, True,
Expand All @@ -3710,7 +3719,8 @@ def __init__(self, widthB=1., lengthB=0.2, angleB=None):
_style_list["-["] = BracketB

class BarAB(_Bracket):
"""An arrow with a bar(|) at both ends.
"""
An arrow with a bar(|) at both ends.
"""

def __init__(self,
Expand All @@ -3719,23 +3729,23 @@ def __init__(self,
"""
Parameters
----------
widthA : float, optional
Width of the bracket
widthA : float, optional, default : 1.
Width of the bracket

lengthA : int
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm slightly confused, __init__ just above this docstring doesn't take a lengthA or lengthB argument, is the docstring just wrong here at the moment?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you're right @dstansby .

@patniharshit can you update this docstring to more accurately reflect the call signature?

Length of the bracket

angleA : float, optional
Angle between the bracket and the line
angleA : float, optional, default : None
Angle between the bracket and the line

widthB : float, optional
Width of the bracket
widthB : float, optional, default : 1.
Width of the bracket

lengthB : int
Length of the bracket

angleB : float, optional
Angle between the bracket and the line
angleB : float, optional, default : None
Angle between the bracket and the line
"""

super(ArrowStyle.BarAB, self).__init__(
Expand All @@ -3745,21 +3755,22 @@ def __init__(self,
_style_list["|-|"] = BarAB

class Simple(_Base):
"""A simple arrow. Only works with a quadratic bezier curve.
"""
A simple arrow. Only works with a quadratic bezier curve.
"""

def __init__(self, head_length=.5, head_width=.5, tail_width=.2):
"""
Parameters
----------
head_length : float, optional
head_length : float, optional, default : .5
Length of the arrow head

head_width : float, optional
Width of the arrow head
head_width : float, optional, default : .5
Width of the arrow head

tail_width : float, optional
Width of the arrow tail
tail_width : float, optional, default : .2
Width of the arrow tail
"""

self.head_length, self.head_width, self.tail_width = \
Expand Down Expand Up @@ -3831,21 +3842,22 @@ def transmute(self, path, mutation_size, linewidth):
_style_list["simple"] = Simple

class Fancy(_Base):
"""A fancy arrow. Only works with a quadratic bezier curve.
"""
A fancy arrow. Only works with a quadratic bezier curve.
"""

def __init__(self, head_length=.4, head_width=.4, tail_width=.4):
"""
Parameters
----------
head_length : float, optional
head_length : float, optional, default : .4
Length of the arrow head

head_with : float, optional
Width of the arrow head
head_width : float, optional, default : .4
Width of the arrow head

tail_width : float, optional
Width of the arrow tail
tail_width : float, optional, default : .4
Width of the arrow tail
"""

self.head_length, self.head_width, self.tail_width = \
Expand Down Expand Up @@ -3943,11 +3955,11 @@ def __init__(self, tail_width=.3, shrink_factor=0.5):
"""
Parameters
----------
tail_width : float, optional
Width of the tail
tail_width : float, optional, default : .3
Width of the tail

shrink_factor : float, optional
Fraction of the arrow width at the middle point
shrink_factor : float, optional, default : 0.5
Fraction of the arrow width at the middle point
"""

self.tail_width = tail_width
Expand Down Expand Up @@ -3990,7 +4002,8 @@ def transmute(self, path, mutation_size, linewidth):


class FancyArrowPatch(Patch):
"""A fancy arrow patch. It draws an arrow using the :class:ArrowStyle.
"""
A fancy arrow patch. It draws an arrow using the :class:ArrowStyle.
"""
_edge_default = True

Expand Down