change: format and add missing docstring placeholders (#945)

This commit will format all existing docstring to follow Google
style: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
This commit will also add docstring placeholders to any class or method
previously missing it.

An ideal approach would be to take the time to include meaningful
docstrings in every file. However, since that is not a task that will
be prioritized, I've declared docstring bankruptcy on this package, in
order to enforce docstring on all future code changes to this package.

Author: knakad

.pylintrc

@@ -92,7 +92,6 @@ disable=
     cyclic-import, # TODO: Resolve cyclic imports
     no-self-use, # TODO: Convert methods to functions where appropriate
     too-many-branches, # TODO: Simplify or ignore as appropriate
-    missing-docstring, # TODO: Fix missing docstring
 
 [REPORTS]
 # Set the output format. Available formats are text, parseable, colorized, msvs

doc/conf.py

@@ -10,6 +10,7 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+"""Placeholder docstring"""
 from __future__ import absolute_import
 
 import os
@@ -22,6 +23,10 @@
 class Mock(MagicMock):
     @classmethod
     def __getattr__(cls, name):
+        """
+        Args:
+            name:
+        """
         if name == "__version__":
             return "1.4.0"
         else:

examples/cli/host/script.py

@@ -6,11 +6,13 @@
 
 
 def model_fn(model_dir):
-    """
-    Load the gluon model. Called once when hosting service starts.
+    """Load the gluon model. Called once when hosting service starts.
+
+    Args:
+        model_dir: The directory where model files are stored.
 
-    :param: model_dir The directory where model files are stored.
-    :return: a model (in this case a Gluon network)
+    Returns:
+        a model (in this case a Gluon network)
     """
     symbol = mx.sym.load("%s/model.json" % model_dir)
     outputs = mx.symbol.softmax(data=symbol, name="softmax_label")
@@ -22,14 +24,16 @@ def model_fn(model_dir):
 
 
 def transform_fn(net, data, input_content_type, output_content_type):
-    """
-    Transform a request using the Gluon model. Called once per request.
+    """Transform a request using the Gluon model. Called once per request.
+
+    Args:
+        net: The Gluon model.
+        data: The request payload.
+        input_content_type: The request content type.
+        output_content_type: The (desired) response content type.
 
-    :param net: The Gluon model.
-    :param data: The request payload.
-    :param input_content_type: The request content type.
-    :param output_content_type: The (desired) response content type.
-    :return: response payload and content type.
+    Returns:
+        response payload and content type.
     """
     # we can use content types to vary input/output handling, but
     # here we just assume json for both

examples/cli/train/script.py

@@ -12,6 +12,12 @@
 def train(channel_input_dirs, hyperparameters, **kwargs):
     # SageMaker passes num_cpus, num_gpus and other args we can use to tailor training to
     # the current container environment, but here we just use simple cpu context.
+    """
+    Args:
+        channel_input_dirs:
+        hyperparameters:
+        **kwargs:
+    """
     ctx = mx.cpu()
 
     # retrieve the hyperparameters we set in notebook (with some defaults)
@@ -80,6 +86,11 @@ def train(channel_input_dirs, hyperparameters, **kwargs):
 
 def save(net, model_dir):
     # save the model
+    """
+    Args:
+        net:
+        model_dir:
+    """
     y = net(mx.sym.var("data"))
     y.save("%s/model.json" % model_dir)
     net.collect_params().save("%s/model.params" % model_dir)
@@ -95,11 +106,21 @@ def define_network():
 
 
 def input_transformer(data, label):
+    """
+    Args:
+        data:
+        label:
+    """
     data = data.reshape((-1,)).astype(np.float32) / 255
     return data, label
 
 
 def get_train_data(data_dir, batch_size):
+    """
+    Args:
+        data_dir:
+        batch_size:
+    """
     return gluon.data.DataLoader(
         gluon.data.vision.MNIST(data_dir, train=True, transform=input_transformer),
         batch_size=batch_size,
@@ -109,6 +130,11 @@ def get_train_data(data_dir, batch_size):
 
 
 def get_val_data(data_dir, batch_size):
+    """
+    Args:
+        data_dir:
+        batch_size:
+    """
     return gluon.data.DataLoader(
         gluon.data.vision.MNIST(data_dir, train=False, transform=input_transformer),
         batch_size=batch_size,
@@ -117,6 +143,12 @@ def get_val_data(data_dir, batch_size):
 
 
 def test(ctx, net, val_data):
+    """
+    Args:
+        ctx:
+        net:
+        val_data:
+    """
     metric = mx.metric.Accuracy()
     for data, label in val_data:
         data = data.as_in_context(ctx)

setup.py

@@ -10,6 +10,7 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+"""Placeholder docstring"""
 from __future__ import absolute_import
 
 import os
@@ -20,6 +21,10 @@
 
 
 def read(fname):
+    """
+    Args:
+        fname:
+    """
     return open(os.path.join(os.path.dirname(__file__), fname)).read()
 
 

src/sagemaker/__init__.py

@@ -10,6 +10,7 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+"""Placeholder docstring"""
 from __future__ import absolute_import
 
 import pkg_resources