Add tracker doc with examples (#63)

* Remove slow marker in conftest

* Move Sagemaker endpoint from Env variable to option

* fix tests

* Fix a integ test

* fix black format

* Improve tracker doc by providing some examples

Author: l2yao

README.rst

@@ -129,4 +129,11 @@ To run the integration tests, the following prerequisites must be met:
 
 .. code-block:: bash
 
-    tox tests/integ
+    tox tests/integ
+
+Generate Docs
+-------------
+
+.. code-block:: bash
+
+    tox -e docs

src/smexperiments/tracker.py

@@ -43,13 +43,6 @@ class Tracker(object):
     end times are automatically set when using the with statement and the trial component is saved to
     SageMaker at the end of the block.
 
-    .. code-block:: python
-
-        with smexperiments.tracker.Tracker.create() as my_tracker:
-            my_tracker.log_parameter('learning_rate', 0.01)
-
-            # Perform data-science code within the with block.
-
     Attributes:
         trial_component (TrialComponent): The trial component tracked.
     """
@@ -79,6 +72,13 @@ def load(
     ):
         """Create a new ``Tracker`` by loading an existing trial component.
 
+        Examples:
+            .. code-block:: python
+
+                from smexperiments import tracker
+
+                my_tracker = tracker.Tracker.load(trial_component_name='xgboost')
+
         Args:
             trial_component_name: (str, optional). The name of the trial component to track. If specified, this
                 trial component must exist in SageMaker. If you invoke this method in a running SageMaker training
@@ -140,6 +140,13 @@ def create(
     ):
         """Create a new ``Tracker`` by creating a new trial component.
 
+        Examples
+            .. code-block:: python
+
+                from smexperiments import tracker
+
+                my_tracker = tracker.Tracker.create()
+
         Args:
             display_name: (str, optional). The display name of the trial component to track.
             artifact_bucket: (str, optional) The name of the S3 bucket to store artifacts to.
@@ -175,6 +182,12 @@ def log_parameter(self, name, value):
 
         Overwrites any previous value recorded for the specified parameter name.
 
+        Examples
+            .. code-block:: python
+
+                # log hyper parameter of learning rate
+                my_tracker.log_parameter('learning_rate', 0.01)
+
         Args:
             name (str): The name of the parameter
             value (str or numbers.Number): The value of the parameter
@@ -184,6 +197,12 @@ def log_parameter(self, name, value):
     def log_parameters(self, parameters):
         """Record a collection of parameter values for this trial component.
 
+        Examples
+            .. code-block:: python
+
+                # log multiple hyper parameters used in training
+                my_tracker.log_parameters({"learning_rate": 1.0, "gamma": 0.9, "dropout": 0.5})
+
         Args:
             parameters (dict[str, str or numbers.Number]): The parameters to record.
         """
@@ -194,6 +213,12 @@ def log_input(self, name, value, media_type=None):
 
         Overwrites any previous value recorded for the specified input name.
 
+        Examples
+            .. code-block:: python
+
+                # log input dataset s3 location
+                my_tracker.log_input(name='input', value='s3://inputs/path')
+
         Args:
             name (str): The name of the input value.
             value (str): The value.
@@ -206,6 +231,12 @@ def log_output(self, name, value, media_type=None):
 
         Overwrites any previous value recorded for the specified output name.
 
+        Examples
+            .. code-block:: python
+
+                # log input dataset s3 location
+                my_tracker.log_output(name='prediction', value='s3://outputs/path')
+
         Args:
             name (str): The name of the output value.
             value (str): The value.
@@ -216,6 +247,12 @@ def log_output(self, name, value, media_type=None):
     def log_artifact(self, file_path, name=None, media_type=None):
         """Upload a local file to s3 and store it as an artifact in this trial component.
 
+        Examples
+            .. code-block:: python
+
+                # log local artifact
+                my_tracker.log_artifact(file_path='/local/path/artifact.tar.gz')
+
         Args:
             file_path (str): The path of the local file to upload.
             name (str, optional): The name of the artifact.
@@ -232,6 +269,14 @@ def log_artifact(self, file_path, name=None, media_type=None):
     def log_metric(self, metric_name, value, timestamp=None, iteration_number=None):
         """Record a scalar metric value for this TrialComponent.
 
+        Examples
+            .. code-block:: python
+
+                for epoch in range(epochs):
+                    # your training logic and calculate accuracy and loss
+                    my_tracker.log_metric(metric_name='accuracy', value=0.9, iteration_number=epoch)
+                    my_tracker.log_metric(metric_name='loss', value=0.03, iteration_number=epoch)
+
         Args:
             metric_name (str): The name of the metric.
             value (number): The value of the metric.