documentation: include pipelines docs in rst and add grammatical fixes (aws#468)

Author: IvyBazan

doc/workflows/index.rst

@@ -9,3 +9,4 @@ The SageMaker Python SDK supports managed training and inference for a variety o
 
     airflow/index
     step_functions/index
+.. pipelines/index

src/sagemaker/workflow/condition_step.py

@@ -35,12 +35,12 @@
 
 
 class ConditionStep(Step):
-    """Conditional step for workflow to support branches in execution of steps.
+    """Conditional step for pipelines to support conditional branching in the execution of steps.
 
     Attributes:
         name (str): The name of the condition step.
         step_type (StepTypeEnum): The type of the step with value `StepTypeEnum.CONDITION`.
-        conditions (List[Condition]): A list of `sagemaker.workflow.conditions.Condition`.
+        conditions (List[Condition]): A list of `sagemaker.workflow.conditions.Condition` instances.
         if_steps (List[Union[Step, StepCollection]]): A list of `sagemaker.workflow.steps.Step`
             and `sagemaker.workflow.step_collections.StepCollection` instances.
         else_steps (List[Union[Step, StepCollection]]): A list of `sagemaker.workflow.steps.Step`
@@ -54,9 +54,9 @@ def __init__(
         if_steps: List[Union[Step, StepCollection]] = None,
         else_steps: List[Union[Step, StepCollection]] = None,
     ):
-        """Constructs a ConditionStep for branch execution.
+        """Constructs a ConditionStep for conditional execution branching.
 
-        If all the conditions in the condition list evaluate to True, the `if_steps` are
+        If all of the conditions in the condition list evaluate to True, the `if_steps` are
         marked as ready for execution. Otherwise, the `else_steps` are marked as ready for
         execution.
 
@@ -65,11 +65,11 @@ def __init__(
             conditions (List[Condition]): A list of `sagemaker.workflow.conditions.Condition`
                 instances.
             if_steps (List[Union[Step, StepCollection]]): A list of `sagemaker.workflow.steps.Step`
-                and `sagemaker.workflow.step_collections.StepCollection` instances that will be
-                marked ready for execution if the list of conditions evaluates to True.
+                and `sagemaker.workflow.step_collections.StepCollection` instances that are
+                marked as ready for execution if the list of conditions evaluates to True.
             else_steps (List[Union[Step, StepCollection]]): A list of `sagemaker.workflow.steps.Step`
-                and `sagemaker.workflow.step_collections.StepCollection` instances that will be
-                marked ready for execution if the list of conditions evaluates to True.
+                and `sagemaker.workflow.step_collections.StepCollection` instances that are
+                marked as ready for execution if the list of conditions evaluates to True.
         """
         super(ConditionStep, self).__init__(name, StepTypeEnum.CONDITION)
         self.conditions = conditions or []
@@ -83,7 +83,7 @@ def __init__(
 
     @property
     def arguments(self) -> RequestType:
-        """The arguments dict that are used to define the condition branching in the pipeline."""
+        """The arguments dict that is used to define the conditional branching in the pipeline."""
         return dict(
             Conditions=[condition.to_request() for condition in self.conditions],
             IfSteps=list_to_request(self.if_steps),
@@ -98,13 +98,13 @@ def properties(self):
 
 @attr.s
 class JsonGet(Expression):
-    """A function to get json properties from PropertyFiles.
+    """A function to get JSON properties from PropertyFiles.
 
     Attributes:
-        step (Step): The step from which to get the property file
+        step (Step): The step from which to get the property file.
         property_file (Union[PropertyFile, str]): Either a PropertyFile instance
-            or a name of a property file.
-        json_path (str): The json path expression to the value of interest.
+            or the name of a property file.
+        json_path (str): The JSON path expression to the requested value.
     """
 
     step: Step = attr.ib()

src/sagemaker/workflow/conditions.py

@@ -68,9 +68,9 @@ class ConditionComparison(Condition):
     Attributes:
         condition_type (ConditionTypeEnum): The type of condition.
         left (ConditionValueType): The execution variable, parameter, or
-            property to use in comparison.
+            property to use in the comparison.
         right (Union[ConditionValueType, PrimitiveType]): The execution variable,
-            parameter, property, or python primitive value to compare to.
+            parameter, property, or Python primitive value to compare to.
     """
 
     left: ConditionValueType = attr.ib(default=None)
@@ -91,19 +91,19 @@ class ConditionEquals(ConditionComparison):
     Attributes:
         condition_type (ConditionTypeEnum): A `ConditionTypeEnum.EQ` type of condition.
         left (ConditionValueType): The execution variable, parameter, or
-            property to use in comparison.
+            property to use in the comparison.
         right (Union[ConditionValueType, PrimitiveType]): The execution variable,
-            parameter, property, or python primitive value to compare to.
+            parameter, property, or Python primitive value to compare to.
     """
 
     def __init__(self, left: ConditionValueType, right: Union[ConditionValueType, PrimitiveType]):
         """Constructs an instance of ConditionEquals.
 
         Args:
             left (ConditionValueType): The execution variable, parameter,
-                or property to use in comparison.
+                or property to use in the comparison.
             right (Union[ConditionValueType, PrimitiveType]): The execution
-                variable, parameter, property, or python primitive value to compare to.
+                variable, parameter, property, or Python primitive value to compare to.
         """
 
         super(ConditionEquals, self).__init__(ConditionTypeEnum.EQ, left, right)
@@ -115,19 +115,19 @@ class ConditionGreaterThan(ConditionComparison):
     Attributes:
         condition_type (ConditionTypeEnum): A `ConditionTypeEnum.GT` type of condition.
         left (ConditionValueType): The execution variable, parameter, or
-            property to use in comparison.
+            property to use in the comparison.
         right (Union[ConditionValueType, PrimitiveType]): The execution variable,
-            parameter, property, or python primitive value to compare to.
+            parameter, property, or Python primitive value to compare to.
     """
 
     def __init__(self, left: ConditionValueType, right: Union[ConditionValueType, PrimitiveType]):
         """Constructs an instance of ConditionGreaterThan.
 
         Args:
             left (ConditionValueType): The execution variable, parameter,
-                or property to use in comparison.
+                or property to use in the comparison.
             right (Union[ConditionValueType, PrimitiveType]): The execution
-                variable, parameter, property, or python primitive value to compare to.
+                variable, parameter, property, or Python primitive value to compare to.
         """
 
         super(ConditionGreaterThan, self).__init__(ConditionTypeEnum.GT, left, right)
@@ -139,19 +139,19 @@ class ConditionGreaterThanOrEqualTo(ConditionComparison):
     Attributes:
         condition_type (ConditionTypeEnum): A `ConditionTypeEnum.GTE` type of condition.
         left (ConditionValueType): The execution variable, parameter, or
-            property to use in comparison.
+            property to use in the comparison.
         right (Union[ConditionValueType, PrimitiveType]): The execution variable,
-            parameter, property, or python primitive value to compare to.
+            parameter, property, or Python primitive value to compare to.
     """
 
     def __init__(self, left: ConditionValueType, right: Union[ConditionValueType, PrimitiveType]):
         """Constructs an instance of ConditionGreaterThanOrEqualTo.
 
         Args:
             left (ConditionValueType): The execution variable, parameter,
-                or property to use in comparison.
+                or property to use in the comparison.
             right (Union[ConditionValueType, PrimitiveType]): The execution
-                variable, parameter, property, or python primitive value to compare to.
+                variable, parameter, property, or Python primitive value to compare to.
         """
 
         super(ConditionGreaterThanOrEqualTo, self).__init__(ConditionTypeEnum.GTE, left, right)
@@ -163,19 +163,19 @@ class ConditionLessThan(ConditionComparison):
     Attributes:
         condition_type (ConditionTypeEnum): A `ConditionTypeEnum.LT` type of condition.
         left (ConditionValueType): The execution variable, parameter, or
-            property to use in comparison.
+            property to use in the comparison.
         right (Union[ConditionValueType, PrimitiveType]): The execution variable,
-            parameter, property, or python primitive value to compare to.
+            parameter, property, or Python primitive value to compare to.
     """
 
     def __init__(self, left: ConditionValueType, right: Union[ConditionValueType, PrimitiveType]):
         """Constructs an instance of ConditionLessThan.
 
         Args:
             left (ConditionValueType): The execution variable, parameter,
-                or property to use in comparison.
+                or property to use in the comparison.
             right (Union[ConditionValueType, PrimitiveType]): The execution
-                variable, parameter, property, or python primitive value to compare to.
+                variable, parameter, property, or Python primitive value to compare to.
         """
 
         super(ConditionLessThan, self).__init__(ConditionTypeEnum.LT, left, right)
@@ -187,26 +187,26 @@ class ConditionLessThanOrEqualTo(ConditionComparison):
     Attributes:
         condition_type (ConditionTypeEnum): A `ConditionTypeEnum.LTE` type of condition.
         left (ConditionValueType): The execution variable, parameter, or
-            property to use in comparison.
+            property to use in the comparison.
         right (Union[ConditionValueType, PrimitiveType]): The execution variable,
-            parameter, property, or python primitive value to compare to.
+            parameter, property, or Python primitive value to compare to.
     """
 
     def __init__(self, left: ConditionValueType, right: Union[ConditionValueType, PrimitiveType]):
         """Constructs an instance of ConditionLessThanOrEqualTo.
 
         Args:
             left (ConditionValueType): The execution variable, parameter,
-                or property to use in comparison.
+                or property to use in the comparison.
             right (Union[ConditionValueType, PrimitiveType]): The execution
-                variable, parameter, property, or python primitive value to compare to.
+                variable, parameter, property, or Python primitive value to compare to.
         """
 
         super(ConditionLessThanOrEqualTo, self).__init__(ConditionTypeEnum.LTE, left, right)
 
 
 class ConditionIn(Condition):
-    """An In condition for negating another `Condition`.
+    """A condition to check membership.
 
     Attributes:
         condition_type (ConditionTypeEnum): A `ConditionTypeEnum.IN` type of condition.
@@ -224,7 +224,7 @@ def __init__(
             value (ConditionValueType): The execution variable,
                 parameter, or property to use for the in comparison.
             in_values (List[Union[ConditionValueType, PrimitiveType]]): The list
-                of values to check the in comparison of.
+                of values to check for membership in.
         """
         super(ConditionIn, self).__init__(ConditionTypeEnum.IN)
         self.value = value
@@ -240,7 +240,7 @@ def to_request(self) -> RequestType:
 
 
 class ConditionNot(Condition):
-    """A Not condition for negating another `Condition`.
+    """A condition for negating another `Condition`.
 
     Attributes:
         condition_type (ConditionTypeEnum): A `ConditionTypeEnum.NOT` type of condition.
@@ -262,11 +262,11 @@ def to_request(self) -> RequestType:
 
 
 class ConditionOr(Condition):
-    """An Or condition for logical OR of a list of `Condition` instances.
+    """A condition for taking the logical OR of a list of `Condition` instances.
 
     Attributes:
         condition_type (ConditionTypeEnum): A `ConditionTypeEnum.OR` type of condition.
-        conditions (List[Condition]): A list of `Condition` to logically OR.
+        conditions (List[Condition]): A list of `Condition` instances to logically OR.
     """
 
     def __init__(self, conditions: List[Condition] = None):
@@ -292,8 +292,7 @@ def primitive_or_expr(
     """Provides the expression of the value or leaves the primitive value alone.
 
     Args:
-        value (Union[ConditionValueType, PrimitiveType]): If it is a
-            PrimitiveType, leave it be. Otherwise, get the expr of the instance.
+        value (Union[ConditionValueType, PrimitiveType]): The value to evaluate..
 
     Returns:
         Either the expression of the value or the primitive value.

src/sagemaker/workflow/execution_variables.py

@@ -38,7 +38,7 @@ def __new__(cls, *args, **kwargs):  # pylint: disable=unused-argument
         return str.__new__(cls, ExecutionVariable._expr(value))
 
     def __init__(self, name: str):
-        """Create a pipeline execution variable.
+        """Creates a pipeline execution variable.
 
         Args:
             name (str): The name of the execution variable.