docs: Add documentation for dbt operators

Author: tomasfarias

airflow_dbt_python/operators/dbt.py

@@ -95,7 +95,14 @@ def __init__(
         self._dbt_s3_hook = None
 
     def execute(self, context: dict):
-        """Execute dbt command with prepared arguments."""
+        """Execute dbt command with prepared arguments.
+
+        Execution requires setting up a directory with the dbt project files and
+        overriding the logging.
+
+        Args:
+            context: The Airflow's task context
+        """
         with self.dbt_directory() as dbt_dir:  # type: str
             with self.override_dbt_logging(dbt_dir):
                 args = self.prepare_args()
@@ -125,6 +132,9 @@ def execute(self, context: dict):
     def xcom_push_artifacts(self, context: dict, dbt_directory: str):
         """Read dbt artifacts and push them to XCom.
 
+        Artifacts are read from the target/ directory in dbt_directory. This method will
+        fail if the required artifact is not found.
+
         Args:
             context: The Airflow task's context.
             dbt_directory: A directory containing a dbt project. Artifacts will be
@@ -160,7 +170,11 @@ def prepare_args(self) -> list[Optional[str]]:
         return args
 
     def args_list(self) -> list[str]:
-        """Build a list of arguments to pass to dbt."""
+        """Build a list of arguments to pass to dbt.
+
+        Building involves creating a list of flags for dbt to parse given the operators
+        attributes and the values specified by __dbt_args__.
+        """
         args = []
         for arg in self.__dbt_args__:
             value = getattr(self, arg, None)
@@ -289,7 +303,12 @@ def serializable_result(
 
 
 class DbtRunOperator(DbtBaseOperator):
-    """Executes dbt run."""
+    """Executes a dbt run command.
+
+    The run command executes SQL model files against the given target. The
+    documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/run.
+    """
 
     command = "run"
 
@@ -337,7 +356,12 @@ def __init__(
 
 
 class DbtSeedOperator(DbtBaseOperator):
-    """Executes dbt seed."""
+    """Executes a dbt seed command.
+
+    The seed command loads csv files into the  the given target. The
+    documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/seed.
+    """
 
     command = "seed"
 
@@ -373,7 +397,12 @@ def __init__(
 
 
 class DbtTestOperator(DbtBaseOperator):
-    """Executes dbt test."""
+    """Executes a dbt test command.
+
+    The test command runs data and/or schema tests. The
+    documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/test.
+    """
 
     command = "test"
 
@@ -424,7 +453,12 @@ def __init__(
 
 
 class DbtCompileOperator(DbtBaseOperator):
-    """Executes dbt compile."""
+    """Executes a dbt compile command.
+
+    The compile command generates SQL files. The
+    documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/compile.
+    """
 
     command = "compile"
 
@@ -469,7 +503,11 @@ def __init__(
 
 
 class DbtDepsOperator(DbtBaseOperator):
-    """Executes dbt deps."""
+    """Executes a dbt deps command.
+
+    The documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/deps.
+    """
 
     command = "deps"
 
@@ -478,7 +516,11 @@ def __init__(self, **kwargs) -> None:
 
 
 class DbtCleanOperator(DbtBaseOperator):
-    """Executes dbt clean."""
+    """Executes a dbt clean command.
+
+    The documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/debug.
+    """
 
     command = "clean"
 
@@ -487,7 +529,11 @@ def __init__(self, **kwargs) -> None:
 
 
 class DbtDebugOperator(DbtBaseOperator):
-    """Execute dbt debug."""
+    """Executes a dbt debug command.
+
+    The documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/debug.
+    """
 
     command = "debug"
 
@@ -505,7 +551,11 @@ def __init__(
 
 
 class DbtSnapshotOperator(DbtBaseOperator):
-    """Execute dbt snapshot."""
+    """Executes a dbt snapshot command.
+
+    The documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/snapshot.
+    """
 
     command = "snapshot"
 
@@ -535,7 +585,11 @@ def __init__(
 
 
 class DbtLsOperator(DbtBaseOperator):
-    """Execute dbt list (or ls)."""
+    """Executes a dbt list (or ls) command.
+
+    The documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/list.
+    """
 
     command = "ls"
 
@@ -572,7 +626,11 @@ def __init__(
 
 
 class DbtRunOperationOperator(DbtBaseOperator):
-    """Execute dbt run-operation."""
+    """Executes a dbt run-operation command.
+
+    The documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/run-operation.
+    """
 
     command = "run-operation"
 
@@ -591,7 +649,11 @@ def __init__(
 
 
 class DbtParseOperator(DbtBaseOperator):
-    """Execute dbt parse."""
+    """Executes a dbt parse command.
+
+    The documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/parse.
+    """
 
     command = "parse"
 
@@ -603,7 +665,11 @@ def __init__(
 
 
 class DbtSourceOperator(DbtBaseOperator):
-    """Execute dbt source."""
+    """Executes a dbt source command.
+
+    The documentation for the dbt command can be found here:
+    https://docs.getdbt.com/reference/commands/source.
+    """
 
     command = "source"
 
@@ -640,7 +706,7 @@ def __init__(
 
 
 class DbtBuildOperator(DbtBaseOperator):
-    """Execute dbt build.
+    """Executes a dbt build command.
 
     The build command combines the run, test, seed, and snapshot commands into one. The
     full Documentation for the dbt build command can be found here: