docs: docstring for cipy.Call

src/cipy/action.py

@@ -14,6 +14,35 @@ from cipy.shell import Shell
 
 
 class Call(Action, extra='allow'):
+    """
+    A wrapper action that allows the passing in of computed arguments, equivalent
+    to GitHub Actions' uses-with pattern. It is not necessary to use a Call Action
+    if all of the input values are known beforehand.
+
+    For example, the following two examples are equivalent to one another:
+
+        github.actions.Checkout(
+            inputs=github.actions.Checkout.Inputs(ref="develop")
+        )
+
+        cipy.Call(
+            github.actions.Checkout(),
+            ref="develop",
+        )
+
+    However, if ref if a computed value, then Call MUST be used.
+
+        github.actions.Checkout(
+            # This part will raise a validation error v~~~~~~~~~~~~~~~~~~~~~~~~~~~~~v
+            inputs=github.actions.Checkout.Inputs(ref=cipy.Ref("inputs.target_branch"))
+        )
+
+        cipy.Call(
+            github.actions.Checkout(),
+            # This is fine, ref will be computed at runtime
+            ref=cipy.Ref("inputs.target_branch")
+        )
+    """
     name: str = ""
     using: Action
     __pydantic_extra__: dict[str, bool | int | float | str | Ref | Factory]