More explicit description for axis insertion in shape_padaxis

doc/library/tensor/basic.txt

@@ -586,7 +586,7 @@ dimensions, see :meth:`_tensor_py_operators.dimshuffle`.
 
 .. function:: shape_padaxis(t, axis)
 
-    Reshape `t` by adding 1 at the dimension `axis`. Note that this new
+    Reshape `t` by inserting 1 at the dimension `axis`. Note that this new
     dimension will be broadcastable. To make it non-broadcastable
     see the :func:`unbroadcast`.
 
@@ -596,6 +596,17 @@ dimensions, see :meth:`_tensor_py_operators.dimshuffle`.
     :type axis: int
     :param  axis: axis where to add the new dimension to `x`
 
+    Example:
+
+    >>> tensor = theano.tensor.tensor3()
+    >>> theano.tensor.shape_padaxis(tensor, axis=0)
+    DimShuffle{x,0,1,2}.0
+    >>> theano.tensor.shape_padaxis(tensor, axis=1)
+    DimShuffle{0,x,1,2}.0
+    >>> theano.tensor.shape_padaxis(tensor, axis=3)
+    DimShuffle{0,1,2,x}.0
+    >>> theano.tensor.shape_padaxis(tensor, axis=-1)
+    DimShuffle{0,1,2,x}.0
 
 .. autofunction:: unbroadcast(x, *axes)
 

theano/tensor/basic.py

@@ -3933,6 +3933,7 @@ def shape_padleft(t, n_ones=1):
 
     See Also
     --------
+    shape_padaxis
     shape_padright
     Dimshuffle
 
@@ -3949,6 +3950,7 @@ def shape_padright(t, n_ones=1):
 
     See Also
     --------
+    shape_padaxis
     shape_padleft
     Dimshuffle
 
@@ -3961,7 +3963,19 @@ def shape_padright(t, n_ones=1):
 
 @constructor
 def shape_padaxis(t, axis):
-    """Reshape `t` by adding 1 at the dimension `axis`.
+    """Reshape `t` by inserting 1 at the dimension `axis`.
+
+    Example
+    -------
+    >>> tensor = theano.tensor.tensor3()
+    >>> theano.tensor.shape_padaxis(tensor, axis=0)
+    DimShuffle{x,0,1,2}.0
+    >>> theano.tensor.shape_padaxis(tensor, axis=1)
+    DimShuffle{0,x,1,2}.0
+    >>> theano.tensor.shape_padaxis(tensor, axis=3)
+    DimShuffle{0,1,2,x}.0
+    >>> theano.tensor.shape_padaxis(tensor, axis=-1)
+    DimShuffle{0,1,2,x}.0
 
     See Also
     --------