Add API documentation for upsampling operator with examples

src/operator/nn/upsampling.cc

@@ -121,9 +121,67 @@ struct UpSamplingGrad {
 DMLC_REGISTER_PARAMETER(UpSamplingParam);
 
 NNVM_REGISTER_OP(UpSampling)
-.describe("Performs nearest neighbor/bilinear up sampling to inputs. "
-          "Bilinear upsampling makes use of deconvolution. Therefore, "
-          "provide 2 inputs - data and weight. ")
+.describe(R"code(Upsamples the given input data.
+
+2 algorithms (``sample_type``) are available for upsampling
+
+- Nearest Neighbor
+- Bilinear
+
+**Nearest Neighbor Upsampling**
+
+Input data is expected to be 4D of the form `(batch, channel, height, width)`.
+
+Example::
+
+  >>> x = nd.ones((1,1,3,3))
+  >>> x
+  [[[[1. 1. 1.]
+     [1. 1. 1.]
+     [1. 1. 1.]]]]
+  <NDArray 1x1x3x3 @cpu(0)>
+  >>> upsampled_x = nd.UpSampling(x, scale=2, sample_type='nearest') 
+  >>> upsampled_x
+  [[[[1. 1. 1. 1. 1. 1.]
+     [1. 1. 1. 1. 1. 1.]
+     [1. 1. 1. 1. 1. 1.]
+     [1. 1. 1. 1. 1. 1.]
+     [1. 1. 1. 1. 1. 1.]
+     [1. 1. 1. 1. 1. 1.]]]]
+  <NDArray 1x1x6x6 @cpu(0)>
+
+**Bilinear Upsampling**
+
+Uses `deconvolution` algorithm under the hood. You need provide both input data and the kernel.
+
+Input data is expected to be 4D of the form `(batch, channel, height, width)`.
+
+`num_filter` is expected to be same as the number of channels.
+
+Example::
+
+  >>> x = nd.ones((1,1,3,3))
+  >>> x
+  [[[[1. 1. 1.]
+     [1. 1. 1.]
+     [1. 1. 1.]]]]
+  <NDArray 1x1x3x3 @cpu(0)>
+  >>> w = nd.ones((1,1,4,4))
+  >>> w
+  [[[[1. 1. 1. 1.]
+     [1. 1. 1. 1.]
+     [1. 1. 1. 1.]
+     [1. 1. 1. 1.]]]]
+  <NDArray 1x1x4x4 @cpu(0)>
+  >>> nd.UpSampling(x, w, scale=2, sample_type='bilinear', num_filter=1)
+  [[[[1. 2. 2. 2. 2. 1.]
+     [2. 4. 4. 4. 4. 2.]
+     [2. 4. 4. 4. 4. 2.]
+     [2. 4. 4. 4. 4. 2.]
+     [2. 4. 4. 4. 4. 2.]
+     [1. 2. 2. 2. 2. 1.]]]]
+  <NDArray 1x1x6x6 @cpu(0)>
+)code" ADD_FILELINE)
 .set_num_inputs([](const NodeAttrs& attrs) {
   const UpSamplingParam& params = nnvm::get<UpSamplingParam>(attrs.parsed);
   return params.sample_type == up_enum::kNearest ? params.num_args : 2;