8000 DOC: formatting fixes to mplot3d by eric-wieser · Pull Request #12033 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

DOC: formatting fixes to mplot3d #12033

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 2 commits into from
Sep 7, 2018
Merged

DOC: formatting fixes to mplot3d #12033

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fa09097
DOC: Use the new documentation style for Axes3D.quiver
eric-wieser Sep 6, 2018
8bfbb8d
DOC: Fix misrendering of kwargs
eric-wieser Sep 6, 2018
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
61 changes: 29 additions & 32 deletions lib/mpl_toolkits/mplot3d/axes3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2402,8 +2402,9 @@ def bar3d(self, x, y, z, dx, dy, dz, color=None,
When true, this shades the dark sides of the bars (relative
to the plot's source of light).

Any additional keyword arguments are passed onto
:func:`~mpl_toolkits.mplot3d.art3d.Poly3DCollection`
**kwargs
Any additional keyword arguments are passed onto
:class:`~mpl_toolkits.mplot3d.art3d.Poly3DCollection`

Returns
-------
Expand Down Expand Up @@ -2483,49 +2484,45 @@ def quiver(self, *args,
length=1, arrow_length_ratio=.3, pivot='tail', normalize=False,
**kwargs):
"""
Plot a 3D field of arrows.

call signatures::

quiver(X, Y, Z, U, V, W, **kwargs)

Arguments:
ax.quiver(X, Y, Z, U, V, W, /, length=1, arrow_length_ratio=.3, pivot='tail', normalize=False, **kwargs)
Copy link
Contributor Author

Choose a reason for hiding this comment

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

This replaces the signature in the docs, using the PEP570 syntax. There's precedent in ax.voxels, but it was admittedly set by me.

Copy link
Member

Choose a reason for hiding this comment

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

I did not look a the code, but if this is like Axes.quiver() this is technically not correct, because you can leave out some of the positional arguments. This is not something one can encode in a single signature line. We therefore use a "Call signatures" block. See the docs of Axes.quiver

Copy link
Contributor Author
@eric-wieser eric-wieser Sep 6, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

All 6 arguments are required to Axes3D.quiver:

        # handle args
        argi = 6
        if len(args) < argi:
            raise ValueError('Wrong number of arguments. Expected %d got %d' %
                             (argi, len(args)))

https://matplotlib.org/devel/documenting_mpl.html doesn't have any mention of "Call signatures" - perhaps it would be worth adding.

Copy link
Member
@timhoffm timhoffm Sep 6, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

If that doc signature is correct, we could directly change the signature of the function to be explicit. But if you don't want to go into this, that's fine as well.

Copy link
Contributor Author
@eric-wieser eric-wieser Sep 6, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

Until PEP570 is implemented, that would involve change the function signature to allow X to be passed by keyword. I think requiring it to be positional is a good idea.


*X*, *Y*, *Z*:
The x, y and z coordinates of the arrow locations (default is
tail of arrow; see *pivot* kwarg)

*U*, *V*, *W*:
The x, y and z components of the arrow vectors
Plot a 3D field of arrows.

The arguments could be array-like or scalars, so long as they
Copy link
Member

Choose a reason for hiding this comment

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

probably should add The arguments *X*, *Y*, *Z*, *U*, *V*, *W* because the context above is deleted.

they can be broadcast together. The arguments can also be
masked arrays. If an element in any of argument is masked, then
that corresponding quiver element will not be plotted.

Keyword arguments:
Parameters
----------
X, Y, Z : array-like
The x, y and z coordinates of the arrow locations (default is
tail of arrow; see *pivot* kwarg)
Copy link
Contributor Author

Choose a reason for hiding this comment

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

I haven't and don't intend to touch any of these descriptions - my goal was only to switch to using Parameters

Copy link
Member

Choose a reason for hiding this comment

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

👍


*length*: [1.0 | float]
The length of each quiver, default to 1.0, the unit is
the same with the axes
U, V, W : array-like
The x, y and z components of the arrow vectors

*arrow_length_ratio*: [0.3 | float]
The ratio of the arrow head with respect to the quiver,
default to 0.3
length : float
The length of each quiver, default to 1.0, the unit is
the same with the axes

*pivot*: [ 'tail' | 'middle' | 'tip' ]
The part of the arrow that is at the grid point; the arrow
rotates about this point, hence the name *pivot*.
Default is 'tail'
arrow_length_ratio : float
The ratio of the arrow head with respect to the quiver,
default to 0.3

*normalize*: bool
When True, all of the arrows will be the same length. This
defaults to False, where the arrows will be different lengths
depending on the values of u,v,w.
pivot : {'tail', 'middle', 'tip'}
The part of the arrow that is at the grid point; the arrow
rotates about this point, hence the name *pivot*.
Default is 'tail'

Any additional keyword arguments are delegated to
:class:`~matplotlib.collections.LineCollection`
normalize : bool
When True, all of the arrows will be the same length. This
defaults to False, where the arrows will be different lengths
depending on the values of u,v,w.

**kwargs
Any additional keyword arguments are delegated to
:class:`~matplotlib.collections.LineCollection`
"""
def calc_arrow(uvw, angle=15):
"""
Expand Down
0