Skip to content

Commit f5e9adb

Browse files
charrischarris
committed
DOC: Fix docstring warnings in documetation generation.
Most of these fixes involve putting blank lines around .. versionadded:: x.x.x and .. deprecated:: x.x.x Some of the examples were also fixed.
1 parent f940a9e commit f5e9adb

File tree

12 files changed

+116
-66
lines changed

12 files changed

+116
-66
lines changed

‎numpy/add_newdocs.py

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -790,14 +790,16 @@ def luf(lamdaexpr, *args, **kwargs):
790790
The shape and data-type of `a` define these same attributes of the
791791
returned array.
792792
dtype : data-type, optional
793-
.. versionadded:: 1.6.0
794793
Overrides the data type of the result.
795-
order : {'C', 'F', 'A', or 'K'}, optional
794+
796795
.. versionadded:: 1.6.0
796+
order : {'C', 'F', 'A', or 'K'}, optional
797797
Overrides the memory layout of the result. 'C' means C-order,
798798
'F' means F-order, 'A' means 'F' if ``a`` is Fortran contiguous,
799799
'C' otherwise. 'K' means match the layout of ``a`` as closely
800800
as possible.
801+
802+
.. versionadded:: 1.6.0
801803
subok : bool, optional.
802804
If True, then the newly created array will use the sub-class
803805
type of 'a', otherwise it will be a base-class array. Defaults
@@ -1703,6 +1705,7 @@ def luf(lamdaexpr, *args, **kwargs):
17031705
Notes
17041706
-----
17051707
.. versionadded:: 1.6.0
1708+
17061709
Starting in NumPy 1.9, promote_types function now returns a valid string
17071710
length when given an integer or float dtype as one argument and a string
17081711
dtype as another argument. Previously it always returned the input string
@@ -5039,10 +5042,10 @@ def luf(lamdaexpr, *args, **kwargs):
50395042
weights : array_like, optional
50405043
Weights, array of the same shape as `x`.
50415044
minlength : int, optional
5042-
.. versionadded:: 1.6.0
5043-
50445045
A minimum number of bins for the output array.
50455046
5047+
.. versionadded:: 1.6.0
5048+
50465049
Returns
50475050
-------
50485051
out : ndarray of ints
@@ -5164,10 +5167,11 @@ def luf(lamdaexpr, *args, **kwargs):
51645167
dims : tuple of ints
51655168
The shape of the array to use for unraveling ``indices``.
51665169
order : {'C', 'F'}, optional
5167-
.. versionadded:: 1.6.0
51685170
Determines whether the indices should be viewed as indexing in
51695171
row-major (C-style) or column-major (Fortran-style) order.
51705172
5173+
.. versionadded:: 1.6.0
5174+
51715175
Returns
51725176
-------
51735177
unraveled_coords : tuple of ndarray

‎numpy/core/defchararray.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2652,7 +2652,7 @@ class adds the following functionality:
26522652
end when comparing values
26532653
26542654
3) vectorized string operations are provided as methods
2655-
(e.g. `str.endswith`) and infix operators (e.g. +, *, %)
2655+
(e.g. `str.endswith`) and infix operators (e.g. ``+``, ``*``,``%``)
26562656
26572657
Parameters
26582658
----------

‎numpy/core/fromnumeric.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1049,10 +1049,11 @@ def searchsorted(a, v, side='left', sorter=None):
10491049
If 'right', return the last such index. If there is no suitable
10501050
index, return either 0 or N (where N is the length of `a`).
10511051
sorter : 1-D array_like, optional
1052-
.. versionadded:: 1.7.0
10531052
Optional array of integer indices that sort array a into ascending
10541053
order. They are typically the result of argsort.
10551054
1055+
.. versionadded:: 1.7.0
1056+
10561057
Returns
10571058
-------
10581059
indices : array of ints

‎numpy/core/numeric.py

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -89,14 +89,16 @@ def zeros_like(a, dtype=None, order='K', subok=True):
8989
The shape and data-type of `a` define these same attributes of
9090
the returned array.
9191
dtype : data-type, optional
92-
.. versionadded:: 1.6.0
9392
Overrides the data type of the result.
94-
order : {'C', 'F', 'A', or 'K'}, optional
93+
9594
.. versionadded:: 1.6.0
95+
order : {'C', 'F', 'A', or 'K'}, optional
9696
Overrides the memory layout of the result. 'C' means C-order,
9797
'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous,
9898
'C' otherwise. 'K' means match the layout of `a` as closely
9999
as possible.
100+
101+
.. versionadded:: 1.6.0
100102
subok : bool, optional.
101103
If True, then the newly created array will use the sub-class
102104
type of 'a', otherwise it will be a base-class array. Defaults
@@ -195,14 +197,16 @@ def ones_like(a, dtype=None, order='K', subok=True):
195197
The shape and data-type of `a` define these same attributes of
196198
the returned array.
197199
dtype : data-type, optional
198-
.. versionadded:: 1.6.0
199200
Overrides the data type of the result.
200-
order : {'C', 'F', 'A', or 'K'}, optional
201+
201202
.. versionadded:: 1.6.0
203+
order : {'C', 'F', 'A', or 'K'}, optional
202204
Overrides the memory layout of the result. 'C' means C-order,
203205
'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous,
204206
'C' otherwise. 'K' means match the layout of `a` as closely
205207
as possible.
208+
209+
.. versionadded:: 1.6.0
206210
subok : bool, optional.
207211
If True, then the newly created array will use the sub-class
208212
type of 'a', otherwise it will be a base-class array. Defaults
@@ -1016,9 +1020,10 @@ def outer(a, b, out=None):
10161020
Second input vector. Input is flattened if
10171021
not already 1-dimensional.
10181022
out : (M, N) ndarray, optional
1019-
.. versionadded:: 1.9.0
10201023
A location where the result is stored
10211024
1025+
.. versionadded:: 1.9.0
1026+
10221027
Returns
10231028
-------
10241029
out : (M, N) ndarray
@@ -1494,6 +1499,7 @@ def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None):
14941499
Notes
14951500
-----
14961501
.. versionadded:: 1.9.0
1502+
14971503
Supports full broadcasting of the inputs.
14981504
14991505
Examples
@@ -2222,10 +2228,11 @@ def allclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False):
22222228
atol : float
22232229
The absolute tolerance parameter (see Notes).
22242230
equal_nan : bool
2225-
.. versionadded:: 1.10.0
22262231
Whether to compare NaN's as equal. If True, NaN's in `a` will be
22272232
considered equal to NaN's in `b` in the output array.
22282233
2234+
.. versionadded:: 1.10.0
2235+
22292236
Returns
22302237
-------
22312238
allclose : bool

‎numpy/distutils/exec_command.py

Lines changed: 50 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
takes keyword arguments for (re-)defining environment variables.
1010
1111
Provides functions:
12+
1213
exec_command --- execute command in a specified directory and
1314
in the modified environment.
1415
find_executable --- locate a command using info from environment
@@ -21,28 +22,33 @@
2122
Requires: Python 2.x
2223
2324
Succesfully tested on:
24-
os.name | sys.platform | comments
25-
--------+--------------+----------
26-
posix | linux2 | Debian (sid) Linux, Python 2.1.3+, 2.2.3+, 2.3.3
27-
PyCrust 0.9.3, Idle 1.0.2
28-
posix | linux2 | Red Hat 9 Linux, Python 2.1.3, 2.2.2, 2.3.2
29-
posix | sunos5 | SunOS 5.9, Python 2.2, 2.3.2
30-
posix | darwin | Darwin 7.2.0, Python 2.3
31-
nt | win32 | Windows Me
32-
Python 2.3(EE), Idle 1.0, PyCrust 0.7.2
33-
Python 2.1.1 Idle 0.8
34-
nt | win32 | Windows 98, Python 2.1.1. Idle 0.8
35-
nt | win32 | Cygwin 98-4.10, Python 2.1.1(MSC) - echo tests
36-
fail i.e. redefining environment variables may
37-
not work. FIXED: don't use cygwin echo!
38-
Comment: also `cmd /c echo` will not work
39-
but redefining environment variables do work.
40-
posix | cygwin | Cygwin 98-4.10, Python 2.3.3(cygming special)
41-
nt | win32 | Windows XP, Python 2.3.3
25+
26+
======== ============ =================================================
27+
os.name sys.platform comments
28+
======== ============ =================================================
29+
posix linux2 Debian (sid) Linux, Python 2.1.3+, 2.2.3+, 2.3.3
30+
PyCrust 0.9.3, Idle 1.0.2
31+
posix linux2 Red Hat 9 Linux, Python 2.1.3, 2.2.2, 2.3.2
32+
posix sunos5 SunOS 5.9, Python 2.2, 2.3.2
33+
posix darwin Darwin 7.2.0, Python 2.3
34+
nt win32 Windows Me
35+
Python 2.3(EE), Idle 1.0, PyCrust 0.7.2
36+
Python 2.1.1 Idle 0.8
37+
nt win32 Windows 98, Python 2.1.1. Idle 0.8
38+
nt win32 Cygwin 98-4.10, Python 2.1.1(MSC) - echo tests
39+
fail i.e. redefining environment variables may
40+
not work. FIXED: don't use cygwin echo!
41+
Comment: also `cmd /c echo` will not work
42+
but redefining environment variables do work.
43+
posix cygwin Cygwin 98-4.10, Python 2.3.3(cygming special)
44+
nt win32 Windows XP, Python 2.3.3
45+
======== ============ =================================================
4246
4347
Known bugs:
44-
- Tests, that send messages to stderr, fail when executed from MSYS prompt
48+
49+
* Tests, that send messages to stderr, fail when executed from MSYS prompt
4550
because the messages are lost at some point.
51+
4652
"""
4753
from __future__ import division, absolute_import, print_function
4854

@@ -148,21 +154,33 @@ def _supports_fileno(stream):
148154
else:
149155
return False
150156

151-
def exec_command( command,
152-
execute_in='', use_shell=None, use_tee = None,
153-
_with_python = 1,
154-
**env ):
155-
""" Return (status,output) of executed command.
156-
157-
command is a concatenated string of executable and arguments.
158-
The output contains both stdout and stderr messages.
159-
The following special keyword arguments can be used:
160-
use_shell - execute `sh -c command`
161-
use_tee - pipe the output of command through tee
162-
execute_in - before run command `cd execute_in` and after `cd -`.
163-
157+
def exec_command(command, execute_in='', use_shell=None, use_tee=None,
158+
_with_python = 1, **env ):
159+
"""
160+
Return (status,output) of executed command.
161+
162+
Parameters
163+
----------
164+
command : str
165+
A concatenated string of executable and arguments.
166+
execute_in : str
167+
Before running command ``cd execute_in`` and after ``cd -``.
168+
use_shell : {bool, None}, optional
169+
If True, execute ``sh -c command``. Default None (True)
170+
use_tee : {bool, None}, optional
171+
If True use tee. Default None (True)
172+
173+
174+
Returns
175+
-------
176+
res : str
177+
Both stdout and stderr messages.
178+
179+
Notes
180+
-----
164181
On NT, DOS systems the returned status is correct for external commands.
165182
Wild cards will not work for non-posix systems or when use_shell=0.
183+
166184
"""
167185
log.debug('exec_command(%r,%s)' % (command,\
168186
','.join(['%s=%r'%kv for kv in env.items()])))

‎numpy/doc/glossary.py

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -264,7 +264,6 @@
264264
(matrix multiplication) and ``**`` (matrix power), defined::
265265
266266
>>> x = np.mat([[1, 2], [3, 4]])
267-
268267
>>> x
269268
matrix([[1, 2],
270269
[3, 4]])
@@ -278,18 +277,17 @@
278277
method called ``repeat``::
279278
280279
>>> x = np.array([1, 2, 3])
281-
282280
>>> x.repeat(2)
283281
array([1, 1, 2, 2, 3, 3])
284282
285283
ndarray
286284
See *array*.
287-
285+
288286
record array
289287
An `ndarray`_ with `structured data type`_ which has been subclassed as
290288
np.recarray and whose dtype is of type np.record, making the
291289
fields of its data type to be accessible by attribute.
292-
290+
293291
reference
294292
If ``a`` is a reference to ``b``, then ``(a is b) == True``. Therefore,
295293
``a`` and ``b`` are different names for the same Python object.
@@ -360,7 +358,6 @@
360358
changed. Similar to a list, it can be indexed and sliced::
361359
362360
>>> x = (1, 'one', [1, 2])
363-
364361
>>> x
365362
(1, 'one', [1, 2])
366363

‎numpy/lib/arraysetops.py

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,10 +114,11 @@ def unique(ar, return_index=False, return_inverse=False, return_counts=False):
114114
If True, also return the indices of the unique array that can be used
115115
to reconstruct `ar`.
116116
return_counts : bool, optional
117-
.. versionadded:: 1.9.0
118117
If True, also return the number of times each unique value comes up
119118
in `ar`.
120119
120+
.. versionadded:: 1.9.0
121+
121122
Returns
122123
-------
123124
unique : ndarray
@@ -129,10 +130,11 @@ def unique(ar, return_index=False, return_inverse=False, return_counts=False):
129130
The indices to reconstruct the (flattened) original array from the
130131
unique array. Only provided if `return_inverse` is True.
131132
unique_counts : ndarray, optional
132-
.. versionadded:: 1.9.0
133133
The number of times each of the unique values comes up in the
134134
original array. Only provided if `return_counts` is True.
135135
136+
.. versionadded:: 1.9.0
137+
136138
See Also
137139
--------
138140
numpy.lib.arraysetops : Module with a number of other functions for

‎numpy/lib/function_base.py

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1146,11 +1146,12 @@ def interp(x, xp, fp, left=None, right=None, period=None):
11461146
Value to return for `x > xp[-1]`, default is `fp[-1]`.
11471147
11481148
period : None or float, optional
1149-
.. versionadded:: 1.10.0
11501149
A period for the x-coordinates. This parameter allows the proper
11511150
interpolation of angular x-coordinates. Parameters `left` and `right`
11521151
are ignored if `period` is specified.
11531152
1153+
.. versionadded:: 1.10.0
1154+
11541155
Returns
11551156
-------
11561157
y : float or ndarray
@@ -1863,23 +1864,26 @@ def cov(m, y=None, rowvar=1, bias=0, ddof=None, fweights=None, aweights=None):
18631864
normalization is by ``N``. These values can be overridden by using the
18641865
keyword ``ddof`` in numpy versions >= 1.5.
18651866
ddof : int, optional
1866-
.. versionadded:: 1.5
18671867
If not ``None`` the default value implied by `bias` is overridden.
18681868
Note that ``ddof=1`` will return the unbiased estimate, even if both
18691869
`fweights` and `aweights` are specified, and ``ddof=0`` will return
18701870
the simple average. See the notes for the details. The default value
18711871
is ``None``.
1872+
1873+
.. versionadded:: 1.5
18721874
fweights : array_like, int, optional
1873-
.. versionadded:: 1.10
18741875
1-D array of integer freguency weights; the number of times each
18751876
observation vector should be repeated.
1876-
aweights : array_like, optional
1877+
18771878
.. versionadded:: 1.10
1879+
aweights : array_like, optional
18781880
1-D array of observation vector weights. These relative weights are
18791881
typically large for observations considered "important" and smaller for
18801882
observations considered less "important". If ``ddof=0`` the array of
18811883
weights can be used to assign probabilities to observation vectors.
18821884
1885+
.. versionadded:: 1.10
1886+
18831887
Returns
18841888
-------
18851889
out : ndarray
@@ -2054,12 +2058,14 @@ def corrcoef(x, y=None, rowvar=1, bias=np._NoValue, ddof=np._NoValue):
20542058
is transposed: each column represents a variable, while the rows
20552059
contain observations.
20562060
bias : _NoValue, optional
2057-
.. deprecated:: 1.10.0
20582061
Has no affect, do not use.
2059-
ddof : _NoValue, optional
2062+
20602063
.. deprecated:: 1.10.0
2064+
ddof : _NoValue, optional
20612065
Has no affect, do not use.
20622066
2067+
.. deprecated:: 1.10.0
2068+
20632069
Returns
20642070
-------
20652071
R : ndarray

‎numpy/lib/npyio.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -745,6 +745,7 @@ def loadtxt(fname, dtype=float, comments='#', delimiter=None,
745745
lines with missing values.
746746
747747
.. versionadded:: 1.10.0
748+
748749
The strings produced by the Python float.hex method can be used as
749750
input for floats.
750751

0 commit comments

Comments
 (0)