add undocumented objects/functions to flytekit api ref (#1502)

* add reference_launch_plan to flytekit api ref Signed-off-by: Niels Bantilan <[email protected]> * import in init, add docstrings Signed-off-by: Niels Bantilan <[email protected]> * add more to references Signed-off-by: Niels Bantilan <[email protected]> * fix lint Signed-off-by: Niels Bantilan <[email protected]> * update Signed-off-by: Niels Bantilan <[email protected]> * fix up docstrings Signed-off-by: Niels Bantilan <[email protected]> --------- Signed-off-by: Niels Bantilan <[email protected]> Co-authored-by: Eduardo Apolinario <[email protected]> Co-authored-by: Samhita Alla <[email protected]>
flyteorg · Feb 13, 2023 · ecded3e · ecded3e
1 parent 8e5bf6c
commit ecded3e
Show file tree

Hide file tree

Showing 6 changed files with 64 additions and 7 deletions.
diff --git a/flytekit/__init__.py b/flytekit/__init__.py
@@ -71,6 +71,18 @@
 
    dynamic
 
+Signaling
+=========
+
+.. autosummary::
+   :nosignatures:
+   :template: custom.rst
+   :toctree: generated/
+
+   approve
+   sleep
+   wait_for_input
+
 Scheduling
 ============================
 
@@ -108,6 +120,7 @@
    WorkflowReference
    reference_task
    reference_workflow
+   reference_launch_plan
 
 Core Task Types
 =================
@@ -153,6 +166,30 @@
    Scalar
    LiteralType
    BlobType
+
+Task Utilities
+==============
+
+.. autosummary::
+   :nosignatures:
+   :template: custom.rst
+   :toctree: generated/
+
+   Deck
+   HashMethod
+
+Documentation
+=============
+
+.. autosummary::
+   :nosignatures:
+   :template: custom.rst
+   :toctree: generated/
+
+   Description
+   Documentation
+   SourceCode
+
 """
 import sys
 from typing import Generator
@@ -172,7 +209,7 @@
 from flytekit.core.dynamic_workflow_task import dynamic
 from flytekit.core.gate import approve, sleep, wait_for_input
 from flytekit.core.hash import HashMethod
-from flytekit.core.launch_plan import LaunchPlan
+from flytekit.core.launch_plan import LaunchPlan, reference_launch_plan
 from flytekit.core.map_task import map_task
 from flytekit.core.notification import Email, PagerDuty, Slack
 from flytekit.core.pod_template import PodTemplate
@@ -239,7 +276,7 @@ def load_implicit_plugins():
         # note the group is always ``flytekit.plugins``
         setup(
         ...
-        entry_points={'flytekit.plugins’: 'fsspec=flytekitplugins.fsspec'},
+        entry_points={'flytekit.plugins': 'fsspec=flytekitplugins.fsspec'},
         ...
         )
 

diff --git a/flytekit/core/gate.py b/flytekit/core/gate.py
@@ -118,7 +118,8 @@ def local_execute(self, ctx: FlyteContext, **kwargs) -> Union[Tuple[Promise], Pr
 
 
 def wait_for_input(name: str, timeout: datetime.timedelta, expected_type: typing.Type):
-    """
+    """Create a Gate object that waits for user input of the specified type.
+
     Create a Gate object. This object will function like a task. Note that unlike a task,
     each time this function is called, a new Python object is created. If a workflow
     calls a subworkflow twice, and the subworkflow has a signal, then two Gate
@@ -136,7 +137,8 @@ def wait_for_input(name: str, timeout: datetime.timedelta, expected_type: typing
 
 
 def sleep(duration: datetime.timedelta):
-    """
+    """Create a sleep Gate object.
+
     :param duration: How long to sleep for
     :return:
     """
@@ -146,7 +148,8 @@ def sleep(duration: datetime.timedelta):
 
 
 def approve(upstream_item: Union[Tuple[Promise], Promise, VoidPromise], name: str, timeout: datetime.timedelta):
-    """
+    """Create a Gate object for binary approval.
+
     Create a Gate object. This object will function like a task. Note that unlike a task,
     each time this function is called, a new Python object is created. If a workflow
     calls a subworkflow twice, and the subworkflow has a signal, then two Gate

diff --git a/flytekit/core/launch_plan.py b/flytekit/core/launch_plan.py
@@ -455,8 +455,15 @@ def reference_launch_plan(
 ) -> Callable[[Callable[..., Any]], ReferenceLaunchPlan]:
     """
     A reference launch plan is a pointer to a launch plan that already exists on your Flyte installation. This
-    object will not initiate a network call to Admin, which is why the user is asked to provide the expected interface.
+    object will not initiate a network call to Admin, which is why the user is asked to provide the expected interface
+    via the function definition.
+
     If at registration time the interface provided causes an issue with compilation, an error will be returned.
+
+    :param project: Flyte project name of the launch plan
+    :param domain: Flyte domain name of the launch plan
+    :param name: launch plan name
+    :param version: specific version of the launch plan to use
     """
 
     def wrapper(fn) -> ReferenceLaunchPlan:

diff --git a/flytekit/core/pod_template.py b/flytekit/core/pod_template.py
@@ -10,6 +10,8 @@
 
 @dataclass
 class PodTemplate(object):
+    """Custom PodTemplate specification for a Task."""
+
     pod_spec: V1PodSpec = V1PodSpec(containers=[])
     primary_container_name: str = PRIMARY_CONTAINER_DEFAULT_NAME
     labels: Optional[Dict[str, str]] = None

diff --git a/flytekit/core/reference_entity.py b/flytekit/core/reference_entity.py
@@ -43,20 +43,26 @@ def resource_type(self) -> int:
 
 @dataclass
 class TaskReference(Reference):
+    """A reference object containing metadata that points to a remote task."""
+
     @property
     def resource_type(self) -> int:
         return _identifier_model.ResourceType.TASK
 
 
 @dataclass
 class LaunchPlanReference(Reference):
+    """A reference object containing metadata that points to a remote launch plan."""
+
     @property
     def resource_type(self) -> int:
         return _identifier_model.ResourceType.LAUNCH_PLAN
 
 
 @dataclass
 class WorkflowReference(Reference):
+    """A reference object containing metadata that points to a remote workflow."""
+
     @property
     def resource_type(self) -> int:
         return _identifier_model.ResourceType.WORKFLOW

diff --git a/flytekit/models/common.py b/flytekit/models/common.py
@@ -414,8 +414,10 @@ def from_flyte_idl(cls, pb):
 
 class AuthRole(FlyteIdlEntity):
     def __init__(self, assumable_iam_role=None, kubernetes_service_account=None):
-        """
+        """Auth configuration for IAM or K8s service account.
+
         Either one or both of the assumable IAM role and/or the K8s service account can be set.
+
         :param Text assumable_iam_role: IAM identity with set permissions policies.
         :param Text kubernetes_service_account: Provides an identity for workflow execution resources.
           Flyte deployment administrators are responsible for handling permissions as they