Skip to content
This repository has been archived by the owner on Nov 17, 2023. It is now read-only.

Fix commands to make doc consistent #14243

Closed
wants to merge 15 commits into from
274 changes: 274 additions & 0 deletions python/mxnet/ndarray_doc.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ class ReshapeDoc(NDArrayDoc):
"""
Examples
--------

Reshapes the input array into a new shape.

>>> x = mx.nd.array([1, 2, 3, 4])
Expand All @@ -54,6 +55,274 @@ class ReshapeDoc(NDArrayDoc):
(4L, 3L, 2L)
"""

class concatDoc(NDArrayDoc):
"""
Examples
--------

Joins input arrays along a given axis.

>>> x = mx.nd.array([[1,1],[2,2]])
ChaiBapchya marked this conversation as resolved.
Show resolved Hide resolved
>>> y = mx.nd.array([[3,3],[4,4],[5,5]])
>>> z = mx.nd.array([[6,6], [7,7],[8,8]])

>>> mx.nd.concat(x,y,z,dim=0)
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm not seeing this show up in the preview...

Copy link
Member

Choose a reason for hiding this comment

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

I do see it. Did you look at the right one?

http://mxnet-ci-doc.s3-accelerate.dualstack.amazonaws.com/PR-14243/7/api/python/ndarray/ndarray.html#mxnet.ndarray.Concat

The preview link is versioned, as mentioned in the pull request checklist:

Copy link
Contributor

Choose a reason for hiding this comment

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

Why does the previous API render the interpreter prompt, but this one does not? It looks close, but I think they're different because it is missing these:
>>> y = mx.nd.array([[3,3],[4,4],[5,5]])

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Any idea why?

Copy link
Member

Choose a reason for hiding this comment

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

Screen Shot 2019-05-11 at 11 35 36 AM

It looks close, but I think they're different because it is missing these:
>>> y = mx.nd.array([[3,3],[4,4],[5,5]])

I did find this. What do you think is missing????

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ya, I guess he was looking at some other preview doc.

[[1. 1.]
[2. 2.]
[3. 3.]
[4. 4.]
[5. 5.]
[6. 6.]
[7. 7.]
[8. 8.]]
<NDArray 8x2 @cpu(0)>

>>> mx.nd.concat(y,z,dim=1)
[[3. 3. 6. 6.]
[4. 4. 7. 7.]
[5. 5. 8. 8.]]
<NDArray 3x4 @cpu(0)>
"""

class SwapAxisDoc(NDArrayDoc):
"""
Examples
--------

Interchanges two axes of an array.
ChaiBapchya marked this conversation as resolved.
Show resolved Hide resolved

>>> x = mx.nd.array([[1, 2, 3]])
>>> mx.nd.swapaxes(x, 0, 1)
[[1.]
[2.]
[3.]]

>>> x = mx.nd.array([[[ 0, 1],[ 2, 3]],[[ 4, 5],[ 6, 7]]])
>>> x
[[[0. 1.]
[2. 3.]]
[[4. 5.]
[6. 7.]]]
<NDArray 2x2x2 @cpu(0)>
>>> mx.nd.swapaxes(x, 0, 2)
[[[0. 4.]
[2. 6.]]
[[1. 5.]
[3. 7.]]]
<NDArray 2x2x2 @cpu(0)>
"""

class whereDoc(NDArrayDoc):
"""
Examples
--------

Return the elements, either from x or y, depending on the condition.

>>> x = mx.nd.array([[1, 2], [3, 4]])
Copy link
Contributor

Choose a reason for hiding this comment

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

This doesn't render right.

>>> y = mx.nd.array([[5, 6], [7, 8]])

>>> cond = mx.nd.array([[0, 1], [-1, 0]])
>>> mx.nd.where(cond, x, y)
[[5. 2.]
[3. 8.]]
<NDArray 2x2 @cpu(0)>

>>> csr_cond = mx.nd.sparse.cast_storage(cond, 'csr')
>>> mx.nd.sparse.where(csr_cond, x, y)
[[5. 2.]
[3. 8.]]
<NDArray 2x2 @cpu(0)>
"""

class ReshapeLikeDoc(NDArrayDoc):
Copy link
Contributor

Choose a reason for hiding this comment

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

How are you deciding when to capitalize?

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 was actually confused. Originally, there were 2 variants
Capitalized - StackDoc, BroadcastToDoc, ReshapeDoc
Non-capitalized - elemwise_addDoc

I am not sure if I understood the difference. Any help on those lines would be great. Thanks for pointing out.

"""
Reshape some or all dimensions of `lhs` to have the same shape as some or all dimensions of `rhs`.
Example
-------

>>> x = mx.nd.array([1, 2, 3, 4, 5, 6])
>>> y = mx.nd.array([[0, -4], [3, 2], [2, 2]])
>>> mx.nd.reshape_like(x, y)
[[1. 2.]
[3. 4.]
[5. 6.]]
<NDArray 3x2 @cpu(0)>
"""

class shape_arrayDoc(NDArrayDoc):
"""
Returns a 1D int64 array containing the shape of data.
Example
-------

>>> x = mx.nd.array([[1,2,3,4], [5,6,7,8]])
>>> mx.nd.shape_array(x)
[2 4]
<NDArray 2 @cpu(0)>
"""

class size_arrayDoc(NDArrayDoc):
"""
Returns a 1D int64 array containing the size of data.
Example
-------

>>> x = mx.nd.array([[1,2,3,4], [5,6,7,8]])
>>> mx.nd.size_array(x)
[8]
<NDArray 1 @cpu(0)>
"""

class CastDoc(NDArrayDoc):
Copy link
Contributor

Choose a reason for hiding this comment

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

Why do you think that return type is gone now? Look at prod, then look a the preview....

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Absolutely no idea why.

"""
Casts all elements of the input to a new type.
Example
-------

>>> x = mx.nd.array([0.9, 1.3])
>>> mx.nd.cast(x, dtype='int32')
[0 1]
<NDArray 2 @cpu(0)>

>>> x = mx.nd.array([1e20, 11.1])
>>> mx.nd.cast(x, dtype='float16')
[ inf 11.1]
<NDArray 2 @cpu(0)>

>>> x = mx.nd.array([300, 11.1, 10.9, -1, -3])
>>> mx.nd.cast(x, dtype='uint8')
[ 44 11 10 255 253]
<NDArray 5 @cpu(0)>
"""

class reciprocalDoc(NDArrayDoc):
"""
Returns the reciprocal of the argument, element-wise.
Example
-------

>>> x = mx.nd.array([-2, 1, 3, 1.6, 0.2])
>>> mx.nd.reciprocal(x)
[-0.5 1. 0.33333334 0.625 5. ]
<NDArray 5 @cpu(0)>
"""

class absDoc(NDArrayDoc):
"""
Returns element-wise absolute value of the input.
Example
-------

>>> x = mx.nd.array([-2, 0, 3])
>>> mx.nd.abs(x)
[2. 0. 3.]
<NDArray 3 @cpu(0)>
"""

class signDoc(NDArrayDoc):
"""
Returns element-wise sign of the input.
Example
-------

>>> x = mx.nd.array([-2, 0, 3])
>>> mx.nd.sign(x)
[-1. 0. 1.]
<NDArray 3 @cpu(0)>
"""

class roundDoc(NDArrayDoc):
"""
Returns element-wise rounded value to the nearest integer of the input.
Example
-------

>>> x = mx.nd.array([-2.1, -1.9, 1.5, 1.9, 2.1])
>>> mx.nd.round(x)
[-2. -2. 2. 2. 2.]
<NDArray 5 @cpu(0)>
"""

class rintDoc(NDArrayDoc):
"""
Returns element-wise rounded value to the nearest integer of the input.
Example
-------

>>> x = mx.nd.array([-2.1, -1.9, 1.5, 1.9, 2.1])
>>> mx.nd.rint(x)
[-2. -2. 1. 2. 2.]
<NDArray 5 @cpu(0)>
"""

class ceilDoc(NDArrayDoc):
"""
Returns element-wise ceiling of the input.
Example
-------

>>> x = mx.nd.array([-2.1, -1.9, 1.5, 1.9, 2.1])
>>> mx.nd.ceil(x)
[-2. -1. 2. 2. 3.]
<NDArray 5 @cpu(0)>
"""

class floorDoc(NDArrayDoc):
"""
Returns element-wise floor of the input.
Example
-------

>>> x = mx.nd.array([-2.1, -1.9, 1.5, 1.9, 2.1])
>>> mx.nd.floor(x)
[-3. -2. 1. 1. 2.]
<NDArray 5 @cpu(0)>
"""

class truncDoc(NDArrayDoc):
"""
Return the element-wise truncated value of the input.
Example
-------

>>> x = mx.nd.array([-2.1, -1.9, 1.5, 1.9, 2.1])
>>> mx.nd.trunc(x)
[-2. -1. 1. 1. 2.]
<NDArray 5 @cpu(0)>
"""

class zeros_likeDoc(NDArrayDoc):
"""
Return an array of zeros with the same shape, type and storage type
Example
-------

>>> x = mx.nd.array([[ 1., 1., 1.],[ 1., 1., 1.]])
>>> x
[[1. 1. 1.]
[1. 1. 1.]]
<NDArray 2x3 @cpu(0)>
>>> mx.nd.zeros_like(x)
[[0. 0. 0.]
[0. 0. 0.]]
<NDArray 2x3 @cpu(0)>
"""

class unravel_indexDoc(NDArrayDoc):
"""
Converts an array of flat indices into a batch of index arrays.
The operator follows numpy conventions so a single multi index is given by a column of the output matrix.
Example
-------

>>> a = mx.nd.array([22,41,37])
>>> mx.nd.unravel_index(a, shape=(7,6))
[[3. 6. 6.]
[4. 5. 1.]]
<NDArray 2x3 @cpu(0)>
"""

class elemwise_addDoc(NDArrayDoc):
"""
Example
Expand All @@ -69,7 +338,9 @@ class BroadcastToDoc(NDArrayDoc):
"""
Examples
--------

Broadcasts the input array into a new shape.

>>> a = mx.nd.array(np.arange(6).reshape(6,1))
>>> b = a.broadcast_to((6,2))
>>> a.shape
Expand Down Expand Up @@ -109,7 +380,9 @@ class StackDoc(NDArrayDoc):
"""
Example
--------

Join a sequence of arrays along a new axis.

>>> x = mx.nd.array([1, 2])
>>> y = mx.nd.array([3, 4])
>>> stack(x, y)
Expand All @@ -124,6 +397,7 @@ class CustomDoc(NDArrayDoc):
"""
Example
-------

Applies a custom operator named `my_custom_operator` to `input`.

>>> output = mx.symbol.Custom(op_type='my_custom_operator', data=input)
Expand Down