doc: add link to parent classes to clarify **kwargs (#1171)

laurenyu · nadiaya · commit 5182be3c147e · 2019-12-17T15:20:00.000-08:00
* doc: add link to parent classes to clarify **kwargs

This commit also fixes some minor Sphinx syntax issues
in the docstrings.

* remove files covered by other PRs
diff --git a/src/sagemaker/algorithm.py b/src/sagemaker/algorithm.py
@@ -1,4 +1,4 @@
-# Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# Copyright 2018-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License"). You
 # may not use this file except in compliance with the License. A copy of
@@ -59,110 +59,72 @@ def __init__(
 
         Args:
             algorithm_arn (str): algorithm arn used for training. Can be just the name if your
-                    account owns the algorithm.
-
-                role (str): An AWS IAM role (either name or full ARN). The Amazon SageMaker
-                    training jobs and APIsthat create Amazon SageMaker endpoints use this role to
-                    access training data and model artifacts. After the endpoint
-                    is created, the inference code might use the IAM role, if it
-                    needs to access an AWS resource.
-
-                train_instance_count (int): Number of Amazon EC2 instances to
+                account owns the algorithm.
+            role (str): An AWS IAM role (either name or full ARN). The Amazon SageMaker
+                training jobs and APIsthat create Amazon SageMaker endpoints use this role to
+                access training data and model artifacts. After the endpoint
+                is created, the inference code might use the IAM role, if it
+                needs to access an AWS resource.
+            train_instance_count (int): Number of Amazon EC2 instances to
                 use for training. train_instance_type (str): Type of EC2
                 instance to use for training, for example, 'ml.c4.xlarge'.
-                train_volume_size (int): Size in GB of the EBS volume to use for
-                storing input data
-
-                    during training (default: 30). Must be large enough to store
-                    training data if File Mode is used (which is the default).
-
-                train_volume_kms_key (str): Optional. KMS key ID for encrypting EBS volume attached
-                    to the training instance (default: None).
-
-                train_max_run (int): Timeout in seconds for training (default: 24 * 60 * 60).
-                    After this amount of time Amazon SageMaker terminates the
-                    job regardless of its current status.
-
-                input_mode (str): The input mode that the algorithm supports
-                (default: 'File'). Valid modes:
-
-                    * 'File' - Amazon SageMaker copies the training dataset from
-                      the S3 location to a local directory.
-                    * 'Pipe' - Amazon SageMaker streams data directly from S3 to
-                      the container via a Unix-named pipe.
-
-                    This argument can be overriden on a per-channel basis using
-                    ``sagemaker.session.s3_input.input_mode``.
-
-                output_path (str): S3 location for saving the training result (model artifacts and
-                    output files). If not specified, results are stored to a default bucket. If
-                    the bucket with the specific name does not exist, the
-                    estimator creates the bucket during the
-                    :meth:`~sagemaker.estimator.EstimatorBase.fit` method
-                    execution.
-
-                output_kms_key (str): Optional. KMS key ID for encrypting the
+            train_volume_size (int): Size in GB of the EBS volume to use for
+                storing input data during training (default: 30). Must be large enough to store
+                training data if File Mode is used (which is the default).
+            train_volume_kms_key (str): Optional. KMS key ID for encrypting EBS volume attached
+                to the training instance (default: None).
+            train_max_run (int): Timeout in seconds for training (default: 24 * 60 * 60).
+                After this amount of time Amazon SageMaker terminates the
+                job regardless of its current status.
+            input_mode (str): The input mode that the algorithm supports
+            (default: 'File'). Valid modes:
+
+                * 'File' - Amazon SageMaker copies the training dataset from
+                  the S3 location to a local directory.
+                * 'Pipe' - Amazon SageMaker streams data directly from S3 to
+                  the container via a Unix-named pipe.
+
+                This argument can be overriden on a per-channel basis using
+                ``sagemaker.session.s3_input.input_mode``.
+
+            output_path (str): S3 location for saving the training result (model artifacts and
+                output files). If not specified, results are stored to a default bucket. If
+                the bucket with the specific name does not exist, the
+                estimator creates the bucket during the
+                :meth:`~sagemaker.estimator.EstimatorBase.fit` method
+                execution.
+            output_kms_key (str): Optional. KMS key ID for encrypting the
                 training output (default: None). base_job_name (str): Prefix for
                 training job name when the
                 :meth:`~sagemaker.estimator.EstimatorBase.fit`
-
-                    method launches. If not specified, the estimator generates a
-                    default job name, based on the training image name and
-                    current timestamp.
-
-                sagemaker_session (sagemaker.session.Session): Session object which manages
-                    interactions with Amazon SageMaker APIs and any other AWS services needed. If
-                    not specified, the estimator creates one using the default
-                    AWS configuration chain.
-
-                tags (list[dict]): List of tags for labeling a training job. For more, see
-                    https://docs.aws.amazon.com/sagemaker/latest/dg/API_Tag.html.
-
-                subnets (list[str]): List of subnet ids. If not specified
+                method launches. If not specified, the estimator generates a
+                default job name, based on the training image name and
+                current timestamp.
+            sagemaker_session (sagemaker.session.Session): Session object which manages
+                interactions with Amazon SageMaker APIs and any other AWS services needed. If
+                not specified, the estimator creates one using the default
+                AWS configuration chain.
+            tags (list[dict]): List of tags for labeling a training job. For more, see
+                https://docs.aws.amazon.com/sagemaker/latest/dg/API_Tag.html.
+            subnets (list[str]): List of subnet ids. If not specified
                 training job will be created without VPC config.
                 security_group_ids (list[str]): List of security group ids. If
-                not specified training job will be created
-
-                    without VPC config.
-
-                model_uri (str): URI where a pre-trained model is stored, either locally or in S3
-                    (default: None). If specified, the estimator will create a channel pointing to
-                    the model so the training job can download it. This model
-                    can be a 'model.tar.gz' from a previous training job, or
-                    other artifacts coming from a different source.
-                    More information:
-                    https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-training.html#td-deserialization
-
-                model_channel_name (str): Name of the channel where 'model_uri'
+                not specified training job will be created without VPC config.
+            model_uri (str): URI where a pre-trained model is stored, either locally or in S3
+                (default: None). If specified, the estimator will create a channel pointing to
+                the model so the training job can download it. This model
+                can be a 'model.tar.gz' from a previous training job, or
+                other artifacts coming from a different source.
+                More information:
+                https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-training.html#td-deserialization
+            model_channel_name (str): Name of the channel where 'model_uri'
                 will be downloaded (default: 'model'). metric_definitions
                 (list[dict]): A list of dictionaries that defines the metric(s)
-                used to evaluate the
-
-                    training jobs. Each dictionary contains two keys: 'Name' for
-                    the name of the metric, and 'Regex' for the regular
-                    expression used to extract the metric from the logs.
-
-                encrypt_inter_container_traffic (bool): Specifies whether traffic between training
-                    containers is encrypted for the training job (default: ``False``).
-            role:
-            train_instance_count:
-            train_instance_type:
-            train_volume_size:
-            train_volume_kms_key:
-            train_max_run:
-            input_mode:
-            output_path:
-            output_kms_key:
-            base_job_name:
-            sagemaker_session:
-            hyperparameters:
-            tags:
-            subnets:
-            security_group_ids:
-            model_uri:
-            model_channel_name:
-            metric_definitions:
-            encrypt_inter_container_traffic:
+                used to evaluate the training jobs. Each dictionary contains two keys: 'Name' for
+                the name of the metric, and 'Regex' for the regular
+                expression used to extract the metric from the logs.
+            encrypt_inter_container_traffic (bool): Specifies whether traffic between training
+                containers is encrypted for the training job (default: ``False``).
             **kwargs: Additional kwargs. This is unused. It's only added for AlgorithmEstimator
                 to ignore the irrelevant arguments.
         """
@@ -309,7 +271,13 @@ def create_model(
                 the model. Default: use subnets and security groups from this Estimator.
                 * 'Subnets' (list[str]): List of subnet ids.
                 * 'SecurityGroupIds' (list[str]): List of security group ids.
-            **kwargs:
+            **kwargs: Additional arguments for creating a :class:`~sagemaker.model.ModelPackage`.
+
+        .. tip::
+
+            You can find additional parameters for using this method at
+            :class:`~sagemaker.model.ModelPackage` and
+            :class:`~sagemaker.model.Model`.
 
         Returns:
             a Model ready for deployment.
diff --git a/src/sagemaker/estimator.py b/src/sagemaker/estimator.py
@@ -1336,9 +1336,15 @@ def create_model(
                 Default: use subnets and security groups from this Estimator.
                 * 'Subnets' (list[str]): List of subnet ids.
                 * 'SecurityGroupIds' (list[str]): List of security group ids.
-            **kwargs:
+            **kwargs: Additional parameters passed to :class:`~sagemaker.model.Model`
+
+        .. tip::
+
+            You can find additional parameters for using this method at
+            :class:`~sagemaker.model.Model`.
 
-        Returns: a Model ready for deployment.
+        Returns:
+            (sagemaker.model.Model) a Model ready for deployment.
         """
         if predictor_cls is None:
 
@@ -1566,6 +1572,11 @@ def __init__(
                 (default: ``None``).
             **kwargs: Additional kwargs passed to the ``EstimatorBase``
                 constructor.
+
+        .. tip::
+
+            You can find additional parameters for initializing this class at
+            :class:`~sagemaker.estimator.EstimatorBase`.
         """
         super(Framework, self).__init__(**kwargs)
         if entry_point.startswith("s3://"):
diff --git a/src/sagemaker/model.py b/src/sagemaker/model.py
@@ -734,6 +734,11 @@ def __init__(
                 try to use either CodeCommit credential helper or local
                 credential storage for authentication.
             **kwargs: Keyword arguments passed to the ``Model`` initializer.
+
+        .. tip::
+
+            You can find additional parameters for initializing this class at
+            :class:`~sagemaker.model.Model`.
         """
         super(FrameworkModel, self).__init__(
             model_data,
diff --git a/src/sagemaker/multidatamodel.py b/src/sagemaker/multidatamodel.py
@@ -66,7 +66,13 @@ def __init__(
                 object, used for SageMaker interactions (default: None). If not
                 specified, one is created using the default AWS configuration
                 chain.
-            **kwargs: Keyword arguments passed to the ``Model`` initializer.
+            **kwargs: Keyword arguments passed to the
+                :class:`~sagemaker.model.Model` initializer.
+
+        .. tip::
+
+            You can find additional parameters for initializing this class at
+            :class:`~sagemaker.model.Model`.
         """
         # Validate path
         if not model_data_prefix.startswith("s3://"):
diff --git a/src/sagemaker/sparkml/model.py b/src/sagemaker/sparkml/model.py
@@ -1,4 +1,4 @@
-# Copyright 2017-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# Copyright 2017-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License"). You
 # may not use this file except in compliance with the License. A copy of
@@ -83,7 +83,13 @@ def __init__(self, model_data, role=None, spark_version=2.2, sagemaker_session=N
                 AWS services needed. If not specified, the estimator creates one
                 using the default AWS configuration chain. For local mode,
                 please do not pass this variable.
-            **kwargs:
+            **kwargs: Additional parameters passed to the
+                :class:`~sagemaker.model.Model` constructor.
+
+        .. tip::
+
+            You can find additional parameters for initializing this class at
+            :class:`~sagemaker.model.Model`.
         """
         # For local mode, sagemaker_session should be passed as None but we need a session to get
         # boto_region_name
diff --git a/src/sagemaker/tuner.py b/src/sagemaker/tuner.py
@@ -401,14 +401,6 @@ def fit(
                 * (list[sagemaker.amazon.amazon_estimator.FileSystemRecordSet]) - A list of
                     :class:~`sagemaker.amazon.amazon_estimator.FileSystemRecordSet` objects,
                     where each instance is a different channel of training data.
-            include_cls_metadata (bool): Whether or not the hyperparameter tuning job should include
-                information about the estimator class (default: False). This information is passed
-                as a hyperparameter, so if the algorithm you are using cannot handle
-                unknown hyperparameters (e.g. an Amazon SageMaker built-in algorithm that
-                does not have a custom estimator in the Python SDK), then set
-                ``include_cls_metadata`` to ``False``.
-            **kwargs: Other arguments needed for training. Please refer to the ``fit()`` method of
-                the associated estimator to see what other arguments are needed.
 
             job_name (str): Tuning job name. If not specified, the tuner
                 generates a default job name, based on the training image name
@@ -426,6 +418,7 @@ def fit(
                     the estimator_dict argument of the method. The keys would be the same
                     estimator names as in estimator_dict. If one estimator doesn't need the flag
                     set, then no need to include it in the dictionary.
+
             estimator_kwargs (dict[str, dict]): Dictionary for other arguments needed for
                 training. Should be used only for tuners created via the factory method create().
                 The keys are the estimator names for the estimator_dict argument of create()
