From 13bf5e22bcd4681de1d33b615ff94f15dd3b768c Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Thu, 8 Feb 2018 18:58:23 +0100 Subject: [PATCH] numpydoc-ify art3d docstrings --- lib/mpl_toolkits/mplot3d/art3d.py | 182 +++++++++++++++++------------- setupext.py | 4 +- 2 files changed, 108 insertions(+), 78 deletions(-) diff --git a/lib/mpl_toolkits/mplot3d/art3d.py b/lib/mpl_toolkits/mplot3d/art3d.py index ef55dd693e1e..3ff3fc58192d 100644 --- a/lib/mpl_toolkits/mplot3d/art3d.py +++ b/lib/mpl_toolkits/mplot3d/art3d.py @@ -2,10 +2,10 @@ # Parts rewritten by Reinier Heeres # Minor additions by Ben Axelrod -''' +""" Module containing 3D artist code and functions to convert 2D artists into 3D versions which can be added to an Axes3D. -''' +""" from __future__ import (absolute_import, division, print_function, unicode_literals) @@ -28,7 +28,7 @@ def norm_angle(a): - """Return angle between -180 and +180""" + """Return the given angle normalized to -180 < *a* <= 180 degrees.""" a = (a + 360) % 360 if a > 180: a = a - 360 @@ -36,7 +36,7 @@ def norm_angle(a): def norm_text_angle(a): - """Return angle between -90 and +90""" + """Return the given angle normalized to -90 < *a* <= 90 degrees.""" a = (a + 180) % 180 if a > 90: a = a - 180 @@ -44,6 +44,26 @@ def norm_text_angle(a): def get_dir_vector(zdir): + """ + Return a direction vector. + + Parameters + ---------- + zdir : {'x', 'y', 'z', None, 3-tuple} + The direction. Possible values are: + - 'x': equivalent to (1, 0, 0) + - 'y': euqivalent to (0, 1, 0) + - 'z': equivalent to (0, 0, 1) + - *None*: euqivalent to (0, 0, 0) + - an iterable (x, y, z) is returned unchanged. + + Returns + ------- + x, y, z : array-like + The direction vector. This is either a numpy.array or *zdir* itself if + *zdir* is already a length-3 iterable. + + """ if zdir == 'x': return np.array((1, 0, 0)) elif zdir == 'y': @@ -59,18 +79,26 @@ def get_dir_vector(zdir): class Text3D(mtext.Text): - ''' - Text object with 3D position and (in the future) direction. - ''' + """ + Text object with 3D position and direction. + + Parameters + ---------- + x, y, z + The position of the text. + text : str + The text string to display. + zdir : {'x', 'y', 'z', None, 3-tuple} + The direction of the text. See `.get_dir_vector` for a description of + the values. + + Other Parameters + ---------------- + **kwargs + All other parameters are passed on to `~matplotlib.text.Text`. + """ def __init__(self, x=0, y=0, z=0, text='', zdir='z', **kwargs): - ''' - *x*, *y*, *z* Position of text - *text* Text string to display - *zdir* Direction of text - - Keyword arguments are passed onto :func:`~matplotlib.text.Text`. - ''' mtext.Text.__init__(self, x, y, text, **kwargs) self.set_3d_properties(z, zdir) @@ -103,14 +131,14 @@ def text_2d_to_3d(obj, z=0, zdir='z'): class Line3D(lines.Line2D): - ''' + """ 3D line object. - ''' + """ def __init__(self, xs, ys, zs, *args, **kwargs): - ''' + """ Keyword arguments are passed onto :func:`~matplotlib.lines.Line2D`. - ''' + """ lines.Line2D.__init__(self, [], [], *args, **kwargs) self._verts3d = xs, ys, zs @@ -137,15 +165,14 @@ def draw(self, renderer): def line_2d_to_3d(line, zs=0, zdir='z'): - ''' - Convert a 2D line to 3D. - ''' + """Convert a 2D line to 3D.""" + line.__class__ = Line3D line.set_3d_properties(zs, zdir) def path_to_3d_segment(path, zs=0, zdir='z'): - '''Convert a path to a 3D segment.''' + """Convert a path to a 3D segment.""" zs = _backports.broadcast_to(zs, len(path)) pathsegs = path.iter_segments(simplify=False, curves=False) @@ -155,9 +182,7 @@ def path_to_3d_segment(path, zs=0, zdir='z'): def paths_to_3d_segments(paths, zs=0, zdir='z'): - ''' - Convert paths from a collection object to 3D segments. - ''' + """Convert paths from a collection object to 3D segments.""" zs = _backports.broadcast_to(zs, len(paths)) segs = [path_to_3d_segment(path, pathz, zdir) @@ -166,7 +191,7 @@ def paths_to_3d_segments(paths, zs=0, zdir='z'): def path_to_3d_segment_with_codes(path, zs=0, zdir='z'): - '''Convert a path to a 3D segment with path codes.''' + """Convert a path to a 3D segment with path codes.""" zs = _backports.broadcast_to(zs, len(path)) seg = [] @@ -180,9 +205,9 @@ def path_to_3d_segment_with_codes(path, zs=0, zdir='z'): def paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'): - ''' + """ Convert paths from a collection object to 3D segments with path codes. - ''' + """ zs = _backports.broadcast_to(zs, len(paths)) segments = [] @@ -195,32 +220,32 @@ def paths_to_3d_segments_with_codes(paths, zs=0, zdir='z'): class Line3DCollection(LineCollection): - ''' + """ A collection of 3D lines. - ''' + """ def __init__(self, segments, *args, **kwargs): - ''' + """ Keyword arguments are passed onto :func:`~matplotlib.collections.LineCollection`. - ''' + """ LineCollection.__init__(self, segments, *args, **kwargs) def set_sort_zpos(self, val): - '''Set the position to use for z-sorting.''' + """Set the position to use for z-sorting.""" self._sort_zpos = val self.stale = True def set_segments(self, segments): - ''' - Set 3D segments - ''' + """ + Set 3D segments. + """ self._segments3d = np.asanyarray(segments) LineCollection.set_segments(self, []) def do_3d_projection(self, renderer): - ''' + """ Project the points according to renderer matrix. - ''' + """ xyslist = [ proj3d.proj_trans_points(points, renderer.M) for points in self._segments3d] @@ -247,9 +272,9 @@ def line_collection_2d_to_3d(col, zs=0, zdir='z'): class Patch3D(Patch): - ''' + """ 3D patch object. - ''' + """ def __init__(self, *args, **kwargs): zs = kwargs.pop('zs', []) @@ -283,9 +308,9 @@ def draw(self, renderer): class PathPatch3D(Patch3D): - ''' + """ 3D PathPatch object. - ''' + """ def __init__(self, path, **kwargs): zs = kwargs.pop('zs', []) @@ -336,9 +361,9 @@ def pathpatch_2d_to_3d(pathpatch, z=0, zdir='z'): class Patch3DCollection(PatchCollection): - ''' + """ A collection of 3D patches. - ''' + """ def __init__(self, *args, **kwargs): """ @@ -363,7 +388,7 @@ def __init__(self, *args, **kwargs): self.set_3d_properties(zs, zdir) def set_sort_zpos(self, val): - '''Set the position to use for z-sorting.''' + """Set the position to use for z-sorting.""" self._sort_zpos = val self.stale = True @@ -404,9 +429,9 @@ def do_3d_projection(self, renderer): class Path3DCollection(PathCollection): - ''' + """ A collection of 3D paths. - ''' + """ def __init__(self, *args, **kwargs): """ @@ -431,7 +456,7 @@ def __init__(self, *args, **kwargs): self.set_3d_properties(zs, zdir) def set_sort_zpos(self, val): - '''Set the position to use for z-sorting.''' + """Set the position to use for z-sorting.""" self._sort_zpos = val self.stale = True @@ -478,15 +503,15 @@ def patch_collection_2d_to_3d(col, zs=0, zdir='z', depthshade=True): (or a :class:`~matplotlib.collections.PathCollection` into a :class:`Path3DCollection` object). - Keywords: - - *za* The location or locations to place the patches in the - collection along the *zdir* axis. Defaults to 0. - - *zdir* The axis in which to place the patches. Default is "z". - - *depthshade* Whether to shade the patches to give a sense of depth. - Defaults to *True*. + Parameters + ---------- + za + The location or locations to place the patches in the collection along + the *zdir* axis. Default: 0. + zdir + The axis in which to place the patches. Default: "z". + depthshade + Whether to shade the patches to give a sense of depth. Default: *True*. """ if isinstance(col, PathCollection): @@ -498,12 +523,12 @@ def patch_collection_2d_to_3d(col, zs=0, zdir='z', depthshade=True): class Poly3DCollection(PolyCollection): - ''' + """ A collection of 3D polygons. - ''' + """ def __init__(self, verts, *args, **kwargs): - ''' + """ Create a Poly3DCollection. *verts* should contain 3D coordinates. @@ -513,7 +538,7 @@ def __init__(self, verts, *args, **kwargs): Note that this class does a bit of magic with the _facecolors and _edgecolors properties. - ''' + """ zsort = kwargs.pop('zsort', True) PolyCollection.__init__(self, verts, *args, **kwargs) self.set_zsort(zsort) @@ -526,11 +551,16 @@ def __init__(self, verts, *args, **kwargs): } def set_zsort(self, zsort): - ''' - Set z-sorting behaviour: - boolean: if True use default 'average' - string: 'average', 'min' or 'max' - ''' + """ + Sets the calculation method for the z-order. + + Parameters + ---------- + zsort : bool or {'average', 'min', 'max'} + For 'average', 'min', 'max' the z-order is determined by applying + the function to the z-coordinates of the vertices in the viewer's + coordinate system. *True* is equivalent to 'average'. + """ if zsort is True: zsort = 'average' @@ -549,7 +579,7 @@ def set_zsort(self, zsort): self.stale = True def get_vector(self, segments3d): - """Optimize points for projection""" + """Optimize points for projection.""" si = 0 ei = 0 segis = [] @@ -571,14 +601,14 @@ def get_vector(self, segments3d): self._segis = segis def set_verts(self, verts, closed=True): - '''Set 3D vertices.''' + """Set 3D vertices.""" self.get_vector(verts) # 2D verts will be updated at draw time PolyCollection.set_verts(self, [], False) self._closed = closed def set_verts_and_codes(self, verts, codes): - '''Sets 3D vertices with path codes''' + """Sets 3D vertices with path codes.""" # set vertices with closed=False to prevent PolyCollection from # setting path codes self.set_verts(verts, closed=False) @@ -597,14 +627,14 @@ def set_3d_properties(self): self.stale = True def set_sort_zpos(self,val): - '''Set the position to use for z-sorting.''' + """Set the position to use for z-sorting.""" self._sort_zpos = val self.stale = True def do_3d_projection(self, renderer): - ''' + """ Perform the 3D projection for this object. - ''' + """ # FIXME: This may no longer be needed? if self._A is not None: self.update_scalarmappable() @@ -673,10 +703,10 @@ def set_edgecolor(self, colors): def set_alpha(self, alpha): """ - Set the alpha tranparencies of the collection. *alpha* must be + Set the alpha transparencies of the collection. *alpha* must be a float or *None*. - ACCEPTS: float or None + .. ACCEPTS: float or None """ if alpha is not None: try: @@ -754,14 +784,14 @@ def rotate_axes(xs, ys, zs, zdir): def get_colors(c, num): - """Stretch the color argument to provide the required number num""" + """Stretch the color argument to provide the required number *num*.""" return _backports.broadcast_to( mcolors.to_rgba_array(c) if len(c) else [0, 0, 0, 0], (num, 4)) def zalpha(colors, zs): - """Modify the alphas of the color list according to depth""" + """Modify the alphas of the color list according to depth.""" # FIXME: This only works well if the points for *zs* are well-spaced # in all three dimensions. Otherwise, at certain orientations, # the min and max zs are very close together. diff --git a/setupext.py b/setupext.py index 99c30128e5f4..b86ee11a9be6 100644 --- a/setupext.py +++ b/setupext.py @@ -1848,10 +1848,10 @@ def convert_qt_version(self, version): return '.'.join(temp) def check_requirements(self): - ''' + """ If PyQt4/PyQt5 is already imported, importing PyQt5/PyQt4 will fail so we need to test in a subprocess (as for Gtk3). - ''' + """ try: p = multiprocessing.Pool()