Document @task sub‐decorators; fix setup/teardown docstrings for Sphinx

task-sdk/docs/api.rst

@@ -33,6 +33,15 @@ Decorators
 .. autoapifunction:: airflow.sdk.dag
 .. autoapifunction:: airflow.sdk.task
 
+Task Decorators:
+
+- ``@task.run_if(condition, skip_message=None)``
+  Run the task only if the given condition is met; otherwise the task is skipped.  The condition is a callable
+  that receives the task execution context and returns either a boolean or a tuple ``(bool, message)``.
+- ``@task.skip_if(condition, skip_message=None)``
+  Skip the task if the given condition is met, raising a skip exception with an optional message.
+- Provider-specific task decorators under ``@task.<provider>``, e.g. ``@task.python``, ``@task.docker``, etc., dynamically loaded from registered providers.
+
 .. autoapifunction:: airflow.sdk.task_group
 
 .. autoapifunction:: airflow.sdk.setup

task-sdk/src/airflow/sdk/definitions/decorators/setup_teardown.py

@@ -35,6 +35,18 @@
 
 
 def setup_task(func: Callable) -> Callable:
+    """
+    Decorate a function to mark it as a setup task.
+
+    A setup task runs before all other tasks in its DAG or TaskGroup context
+    and can perform initialization or resource preparation.
+
+    Example::
+
+        @setup
+        def initialize_context(...):
+            ...
+    """
     # Using FunctionType here since _TaskDecorator is also a callable
     if isinstance(func, types.FunctionType):
         func = python_task(func)
@@ -45,6 +57,19 @@ def setup_task(func: Callable) -> Callable:
 
 
 def teardown_task(_func=None, *, on_failure_fail_dagrun: bool = False) -> Callable:
+    """
+    Decorate a function to mark it as a teardown task.
+
+    A teardown task runs after all main tasks in its DAG or TaskGroup context.
+    If ``on_failure_fail_dagrun=True``, a failure in teardown will mark the DAG run as failed.
+
+    Example::
+
+        @teardown(on_failure_fail_dagrun=True)
+        def cleanup(...):
+            ...
+    """
+
     def teardown(func: Callable) -> Callable:
         # Using FunctionType here since _TaskDecorator is also a callable
         if isinstance(func, types.FunctionType):