additional detail in documentation

Author: danabens

docs/index.rst

@@ -1,11 +1,18 @@
 Amazon SageMaker Experiments Python SDK
 =======================================
 
+Amazon SageMaker Experiments Python SDK is an open source library for tracking machine learning experiments.
+
+With the SDK you can track and organize your machine learning workflow across SageMaker with jobs such as Processing, Training, and Transform.
+
+Here you'll find an overview and API documentation.  The project homepage is on GitHub: https://github.com/aws/sagemaker-experiments, where you can find the SDK source and installation instructions for the library.
+
 .. toctree::
     :maxdepth: 1
 
     tracker
     experiment
     trial
     trial_component
-    metrics
+    metrics
+    links

docs/links.rst

@@ -0,0 +1,6 @@
+Links
+-----
+
+* `Manage Machine Learning with Amazon SageMaker Experiments <https://docs.aws.amazon.com/sagemaker/latest/dg/experiments.html>`_
+* `Track and Evaluate a Model Training Experiment <https://docs.aws.amazon.com/sagemaker/latest/dg/experiments-mnist.html>`_
+* `SageMaker Experiments example notebooks <https://github.com/awslabs/amazon-sagemaker-examples/tree/master/sagemaker-experiments>`_

src/smexperiments/_base_types.py

@@ -16,10 +16,12 @@
 
 
 class ApiObject(object):
-    """A Python class representation of a boto API object. Converts boto dicts of 'UpperCamelCase' names
+    """
+    A Python class representation of a boto API object. Converts boto dicts of 'UpperCamelCase' names
     to dicts into/from a Python object with standard python members. Clients invoke to_boto on an instance
      of ApiObject to transform the ApiObject into a boto representation. Clients invoke from_boto on a sub-class of
-     ApiObject to instantiate an instance of that class from a boto representation."""
+     ApiObject to instantiate an instance of that class from a boto representation.
+     """
 
     # A map from boto 'UpperCamelCase' name to member name. If a boto name does not appear in this dict then
     # it is converted to lower_snake_case.
@@ -37,7 +39,12 @@ def _boto_ignore(cls):
 
     @classmethod
     def from_boto(cls, boto_dict, **kwargs):
-        """Construct an instance of this ApiObject from a boto response."""
+        """Construct an instance of this ApiObject from a boto response.
+
+        Args:
+            boto_dict (dict): A dictionary of a boto response.
+            **kwargs: Arbitrary keyword arguments
+        """
         boto_dict = {k: v for k, v in boto_dict.items() if k not in cls._boto_ignore()}
         custom_boto_names_to_member_names = {a: b for b, a in cls._custom_boto_names.items()}
         cls_kwargs = _boto_functions.from_boto(boto_dict, custom_boto_names_to_member_names, cls._custom_boto_types)
@@ -46,7 +53,11 @@ def from_boto(cls, boto_dict, **kwargs):
 
     @classmethod
     def to_boto(cls, obj):
-        """Convert an object to a boto representation."""
+        """Convert an object to a boto representation.
+
+        Args:
+            obj (dict): The object to convert to boto.
+        """
         if not isinstance(obj, dict):
             var_dict = vars(obj)
         else:
@@ -127,7 +138,11 @@ def _construct(cls, boto_method_name, sagemaker_boto_client=None, **kwargs):
         return instance._invoke_api(boto_method_name, kwargs)
 
     def with_boto(self, boto_dict):
-        """Update this ApiObject with a boto response."""
+        """Update this ApiObject with a boto response.
+
+        Args:
+            boto_dict (dict): A dictionary of a boto response.
+        """
         custom_boto_names_to_member_names = {a: b for b, a in self._custom_boto_names.items()}
         self.__dict__.update(
             **_boto_functions.from_boto(boto_dict, custom_boto_names_to_member_names, self._custom_boto_types)

src/smexperiments/_boto_functions.py

@@ -15,27 +15,45 @@
 
 
 def to_camel_case(snake_case):
-    """Convert a snake case string to camel case"""
+    """Convert a snake case string to camel case.
+
+    Args:
+        snake_case (str): String to convert to camel case.
+
+    Returns:
+        str: String converted to camel case.
+    """
     return "".join([x.title() for x in snake_case.split("_")])
 
 
 def to_snake_case(name):
-    """Convert a camel case string to snake case"""
+    """Convert a camel case string to snake case
+
+    Args:
+        name (str): String to convert to snake case.
+
+    Returns:
+        str: String converted to snake case.
+    """
     # https://stackoverflow.com/questions/1175208/elegant-python-function-to-convert-camelcase-to-snake-case
     s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
     return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
 
 
 def from_boto(boto_dict, boto_name_to_member_name, member_name_to_type):
-    """Convert an UpperCamelCase boto response to a snake case representation.
+    """
+    Convert an UpperCamelCase boto response to a snake case representation.
 
-       Args:
-           boto_dict dict[str, ?]: A boto response dictionary.
-           boto_name_to_member_name dict[str, str]: A map from boto name to snake_case name. If a given boto name is
-               not in the map then a default mapping is applied.
-           member_name_to_type dict[str, (_base_types.ApiObject, boolean)]: A map from snake case name to a type
-              description tuple. The first element of the tuple, a sublcass of ApiObject, is the type of the mapped
-              object. The second element indicates whether the mapped element is a collection or singleton.
+    Args:
+        boto_dict (dict[str, ?]): A boto response dictionary.
+        boto_name_to_member_name (dict[str, str]):  A map from boto name to snake_case name. If a given boto name is
+            not in the map then a default mapping is applied.
+        member_name_to_type (dict[str, (_base_types.ApiObject, boolean)]): A map from snake case name to a type
+            description tuple. The first element of the tuple, a subclass of ApiObject, is the type of the mapped
+            object. The second element indicates whether the mapped element is a collection or singleton.
+
+    Returns:
+        dict: Boto response in snake case.
     """
     from_boto_values = {}
     for boto_name, boto_value in boto_dict.items():
@@ -68,6 +86,10 @@ def to_boto(member_vars, member_name_to_boto_name, member_name_to_type):
        Args:
            member_vars dict[str, ?]: A map from snake case name to value.
            member_name_to_boto_name dict[str, ?]: A map from snake_case name to boto name.
+
+        Returns:
+            dict: boto dict converted to snake case
+
     """
     to_boto_values = {}
     # Strip out all entries in member_vars that have a None value. None values are treated as not having a value

src/smexperiments/_environment.py

@@ -10,11 +10,21 @@
 
 
 class EnvironmentType(enum.Enum):
+    """
+    SageMaker jobs which data can be pulled from the environment.
+    """
+
     SageMakerTrainingJob = 1
     SageMakerProcessingJob = 2
 
 
 class TrialComponentEnvironment(object):
+    """Retrieves job specific data from the environment.
+
+    Attributes:
+        environment_type (EnvironmentType): The environment type.
+        source_arn (str): The arn of the current job.
+    """
 
     environment_type = None
     source_arn = None
@@ -25,6 +35,15 @@ def __init__(self, environment_type, source_arn):
 
     @classmethod
     def load(cls, training_job_arn_env=TRAINING_JOB_ARN_ENV, processing_job_config_path=PROCESSING_JOB_CONFIG_PATH):
+        """Loads source arn of current job from environment.
+
+        Args:
+            training_job_arn_env (str): The environment key for training job arn.
+            processing_job_config_path (str): The processing job config path.
+
+        Returns:
+            TrialComponentEnvironment: Job data loaded from the environment. None if config does not exist.
+        """
         if training_job_arn_env in os.environ:
             environment_type = EnvironmentType.SageMakerTrainingJob
             source_arn = os.environ.get(training_job_arn_env)
@@ -37,6 +56,14 @@ def load(cls, training_job_arn_env=TRAINING_JOB_ARN_ENV, processing_job_config_p
             return None
 
     def get_trial_component(self, sagemaker_boto_client):
+        """Retrieves the trial component from the job in the environment.
+
+        Args:
+            sagemaker_boto_client (SageMaker.Client): SageMaker boto client.
+
+        Returns:
+            TrialComponent: The trial component created from the job. None if not found.
+        """
         start = time.time()
         while time.time() - start < 300:
             summaries = list(

src/smexperiments/_utils.py

@@ -20,13 +20,23 @@
 
 
 def sagemaker_client():
+    """Instantiates a SageMaker client.
+
+    Returns:
+        SageMaker.Client
+    """
     if os.environ.get("SAGEMAKER_ENDPOINT", "").strip():
         return boto_session().client("sagemaker", endpoint_url=os.environ.get("SAGEMAKER_ENDPOINT"))
     else:
         return boto_session().client("sagemaker")
 
 
 def boto_session():
+    """Instantiates a boto Session.
+
+    Returns:
+        boto3.Session
+    """
     return boto3.Session(region_name=os.environ.get("AWS_REGION"))
 
 
@@ -42,6 +52,16 @@ def name(prefix):
 
 
 def get_or_create_default_bucket(boto_session, default_bucket_prefix="sagemaker"):
+    """Creates a default bucket if not already exists. The bucket name is a combination of a prefix, the region, and
+    account.
+
+    Args:
+        boto_session (boto3.Session): boto session
+        default_bucket_prefix (str): prefix to the bucket name
+
+    Returns:
+        str: The default bucket name.
+    """
     account = boto_session.client("sts").get_caller_identity()["Account"]
     region = boto_session.region_name
     default_bucket = "{}-{}-{}".format(default_bucket_prefix, region, account)