Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

MEP10 - refactored hlines and vlines documentation #1795

Merged
merged 4 commits into from

3 participants

@NelleV
Collaborator

Refactored hlines and vlines documentation to match MEP10

Thanks,
N

lib/matplotlib/axes.py
((47 lines not shown))
- %(LineCollection)s
@pelson Collaborator
pelson added a note

Have the contents of this now been included directly?

@NelleV Collaborator
NelleV added a note

Nope, this is lost. Using this trick doesn't work (it is not rendered properly), and numpydoc has no way to do introspection to spot that these are linecollection kwargs.

@mdboom Owner
mdboom added a note

I know that whether to continue to include these inline was controversial -- but I tend to fall on the side of not duplicating this information everywhere. If we do that, though, we need a clear link to the LineProperties class, and my suggested change for the Returns section above does that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
lib/matplotlib/axes.py
((32 lines not shown))
- kwargs are :class:`~matplotlib.collections.LineCollection` properties:
+ Returns
+ -------
+ matplotlib.collections.LineCollection
@mdboom Owner
mdboom added a note

This has to be of the form name : type or it doesn't render correctly, i.e.

lines : matplotlib.collections.LineCollection
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
lib/matplotlib/axes.py
((32 lines not shown))
- kwargs are :class:`~matplotlib.collections.LineCollection` properties:
+ Returns
+ -------
+ matplotlib.collections.LineCollection
+
+ Other parameters
+ ----------------
+ kwargs correspond to matplotlib.collections.LineCollection properties.
+
+ Notes
+ -----
+ .. plot:: mpl_examples/pylab_examples/vline_hline_demo.py
@mdboom Owner
mdboom added a note

Notes needs to come after See also (again, it doesn't render correctly).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
lib/matplotlib/axes.py
((32 lines not shown))
- kwargs are :class:`~matplotlib.collections.LineCollection` properties:
+ Returns
+ -------
+ matplotlib.collections.LineCollection
+
+ Other parameters
+ ----------------
+ kwargs correspond to matplotlib.collections.LineCollection properties.
@mdboom Owner
mdboom added a note

This doesn't render correctly, plus it would be nice if it linked to the LineCollection class:

kwargs : `~matplotlib.collections.LineCollection` properties
@NelleV Collaborator
NelleV added a note

Maybe this should fall in the Notes section ?

@mdboom Owner
mdboom added a note

Well, they are "Other Parameters" -- it sort of makes sense there, but it does mean we have to use numpydoc's parameter syntax here. Saying "kwargs" as a parameter name is a bit clunky/obscure, though, admittedly.

@NelleV Collaborator
NelleV added a note

It's fixed !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mdboom
Owner

This looks good -- this is the first time I've spent the time to actually build and look at the output of your MEP10 changes. It looks great -- but sorry if I'm commenting on issues that may have already gone a different way in earlier PRs (such as how the Returns section is written etc.)

@NelleV
Collaborator

For the curious, I just set up an automatic build of the documentation of the master branch of the repository here:
http://cbio.ensmp.fr/~nvaroquaux/matplotlib/doc/ and a check of the flake8 report here (but links don't work):
http://cbio.ensmp.fr/~nvaroquaux/matplotlib/flake8_report/

The flake8 report could be done by shining panda, or something more adapted than bash scripts.

@mdboom
Owner

Thanks. Once we get funding in place, I hope to set up a Shining Panda pro account for matplotlib soon -- and this is definitely the kind of useful thing to do over there.

@mdboom
Owner

Great. I think it's good (as we doing here) to get the first few docstrings really right and then running through the rest should involve a lot of just following the same pattern.

@NelleV
Collaborator

I think this is ready to be merged.

@mdboom
Owner

I'm seeing funky formatting when building this. It looks like "Other Parameters" is divided into two sections...?
funky-formatting

@NelleV
Collaborator

Other parameters can have a list of parameter as the "parameters" section has, so I think this is normal.

@mdboom
Owner

But why is it on a different background color, with a line above it (unlike Parameters above)? It looks like it's in a different section (at least to my eyes).

@NelleV
Collaborator

It is either the way it is supposed to be or a bug in numpydoc. After digging in numpy and scipy's code, I finnaly found a place where this was used:http://docs.scipy.org/doc/scipy/reference/generated/scipy.weave.inline.html#scipy.weave.inline

There's nothing much we can do about that, except submit a patch to numpydoc.

@mdboom
Owner

Ok thanks for looking into it. Since it's not anything we can fix from our end, I'll go ahead and merge this. Thanks.

@mdboom mdboom merged commit 9690232 into matplotlib:master
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
View
2  examples/pylab_examples/README
@@ -13,7 +13,7 @@ Here are some demos of how to use the matplotlib.
-- subplot_demo.py - how to do multiple axes on a single plot
--- vline_demo.py - working with straight lines
+-- vline_hline_demo.py - working with straight lines
-- stock_demo.py - working with large datasets. Click on the plot and
launch the navigation tool; wheel mouse over the navigation
View
23 examples/pylab_examples/hline_demo.py
@@ -1,23 +0,0 @@
-#!/usr/bin/env python
-import numpy as np
-import matplotlib.pyplot as plt
-
-def f(t):
- s1 = np.sin(2*np.pi*t)
- e1 = np.exp(-t)
- return np.absolute((s1*e1))+.05
-
-
-t = np.arange(0.0, 5.0, 0.1)
-s = f(t)
-nse = np.random.normal(0.0, 0.3, t.shape) * s
-
-
-plt.plot(s+nse, t, 'b^')
-plt.hlines(t, [0], s, lw=2)
-plt.xlabel('time (s)')
-plt.title('Comparison of model with data')
-
-plt.xlim(xmin=0)
-plt.show()
-
View
21 examples/pylab_examples/vline_demo.py
@@ -1,21 +0,0 @@
-#!/usr/bin/env python
-from matplotlib.pyplot import *
-from numpy import sin, exp, absolute, pi, arange
-from numpy.random import normal
-
-def f(t):
- s1 = sin(2*pi*t)
- e1 = exp(-t)
- return absolute((s1*e1))+.05
-
-
-t = arange(0.0, 5.0, 0.1)
-s = f(t)
-nse = normal(0.0, 0.3, t.shape) * s
-
-plot(t, s+nse, 'b^')
-vlines(t, [0], s)
-xlabel('time (s)')
-title('Comparison of model with data')
-show()
-
View
36 examples/pylab_examples/vline_hline_demo.py
@@ -0,0 +1,36 @@
+#!/usr/bin/env python
+
+"""
+Small demonstration of the hlines and vlines plots.
+"""
+
+from matplotlib import pyplot as plt
+from numpy import sin, exp, absolute, pi, arange
+from numpy.random import normal
+
+
+def f(t):
+ s1 = sin(2 * pi * t)
+ e1 = exp(-t)
+ return absolute((s1 * e1)) + .05
+
+
+t = arange(0.0, 5.0, 0.1)
+s = f(t)
+nse = normal(0.0, 0.3, t.shape) * s
+
+fig = plt.figure(figsize=(12, 6))
+vax = fig.add_subplot(121)
+hax = fig.add_subplot(122)
+
+vax.plot(t, s + nse, 'b^')
+vax.vlines(t, [0], s)
+vax.set_xlabel('time (s)')
+vax.set_title('Vertical lines demo')
+
+hax.plot(s + nse, t, 'b^')
+hax.hlines(t, [0], s, lw=2)
+hax.set_xlabel('time (s)')
+hax.set_title('Horizontal lines demo')
+
+plt.show()
View
3  examples/tests/backend_driver.py
@@ -113,7 +113,7 @@
'hist_colormapped.py',
'histogram_demo.py',
'histogram_demo_extended.py',
- 'hline_demo.py',
+ 'vline_hline_demo.py',
'image_clip_path.py',
'image_demo.py',
@@ -199,7 +199,6 @@
'transoffset.py',
'unicode_demo.py',
'vertical_ticklabels.py',
- 'vline_demo.py',
'xcorr_demo.py',
'zorder_demo.py',
]
View
88 lib/matplotlib/axes.py
@@ -3656,37 +3656,39 @@ def hlines(self, y, xmin, xmax, colors='k', linestyles='solid',
"""
Plot horizontal lines.
- call signature::
+ Plot horizontal lines at each `y` from `xmin` to `xmax`.
- hlines(y, xmin, xmax, colors='k', linestyles='solid', **kwargs)
+ Parameters
+ ----------
+ y : scalar or 1D array_like
+ y-indexes where to plot the lines.
- Plot horizontal lines at each *y* from *xmin* to *xmax*.
+ xmin, xmax : scalar or 1D array_like
+ Respective beginning and end of each line. If scalars are
+ provided, all lines will have same length.
- Returns the :class:`~matplotlib.collections.LineCollection`
- that was added.
+ colors : array_like of colors, optional, default: 'k'
- Required arguments:
+ linestyles : ['solid' | 'dashed' | 'dashdot' | 'dotted'], optional
- *y*:
- a 1-D numpy array or iterable.
+ label : string, optional, default: ''
- *xmin* and *xmax*:
- can be scalars or ``len(x)`` numpy arrays. If they are
- scalars, then the respective values are constant, else the
- widths of the lines are determined by *xmin* and *xmax*.
-
- Optional keyword arguments:
+ Returns
+ -------
+ lines : `~matplotlib.collections.LineCollection`
- *colors*:
- a line collections color argument, either a single color
- or a ``len(y)`` list of colors
+ Other parameters
+ ----------------
+ kwargs : `~matplotlib.collections.LineCollection` properties.
- *linestyles*:
- [ 'solid' | 'dashed' | 'dashdot' | 'dotted' ]
+ See also
+ --------
+ vlines : vertical lines
- **Example:**
+ Examples
+ --------
+ .. plot:: mpl_examples/pylab_examples/vline_hline_demo.py
- .. plot:: mpl_examples/pylab_examples/hline_demo.py
"""
# We do the conversion first since not all unitized data is uniform
@@ -3743,27 +3745,39 @@ def vlines(self, x, ymin, ymax, colors='k', linestyles='solid',
"""
Plot vertical lines.
- Call signature::
+ Plot vertical lines at each `x` from `ymin` to `ymax`.
- vlines(x, ymin, ymax, color='k', linestyles='solid')
+ Parameters
+ ----------
+ x : scalar or 1D array_like
+ x-indexes where to plot the lines.
- Plot vertical lines at each *x* from *ymin* to *ymax*. *ymin*
- or *ymax* can be scalars or len(*x*) numpy arrays. If they are
- scalars, then the respective values are constant, else the
- heights of the lines are determined by *ymin* and *ymax*.
+ xmin, xmax : scalar or 1D array_like
+ Respective beginning and end of each line. If scalars are
+ provided, all lines will have same length.
- *colors* :
- A line collection's color args, either a single color
- or a ``len(x)`` list of colors
+ colors : array_like of colors, optional, default: 'k'
- *linestyles* : [ 'solid' | 'dashed' | 'dashdot' | 'dotted' ]
+ linestyles : ['solid' | 'dashed' | 'dashdot' | 'dotted'], optional
- Returns the :class:`matplotlib.collections.LineCollection`
- that was added.
+ label : string, optional, default: ''
- kwargs are :class:`~matplotlib.collections.LineCollection` properties:
+ Returns
+ -------
+ lines : `~matplotlib.collections.LineCollection`
+
+ Other parameters
+ ----------------
+ kwargs : `~matplotlib.collections.LineCollection` properties.
+
+ See also
+ --------
+ hlines : horizontal lines
+
+ Examples
+ ---------
+ .. plot:: mpl_examples/pylab_examples/vline_hline_demo.py
- %(LineCollection)s
"""
self._process_unit_info(xdata=x, ydata=[ymin, ymax], kwargs=kwargs)
@@ -8322,8 +8336,6 @@ def hist(self, x, bins=10, range=None, normed=False, weights=None,
mlast[:] = m
n.append(m)
-
-
if cumulative:
slc = slice(None)
if cbook.is_numlike(cumulative) and cumulative < 0:
@@ -8405,7 +8417,7 @@ def hist(self, x, bins=10, range=None, normed=False, weights=None,
# For normed data, set to log base * minimum data value
# (gives 1 full tick-label unit for the lowest filled bin)
ndata = np.array(n)
- minimum = (np.min(ndata[ndata>0])) / logbase
+ minimum = (np.min(ndata[ndata > 0])) / logbase
else:
# For non-normed data, set the min to log base, again so
# that there is 1 full tick-label unit for the lowest bin
Something went wrong with that request. Please try again.