docs: add api docs to magic initiate

uaclient/api/exceptions.py

@@ -11,6 +11,7 @@
     IncompatibleServiceStopsEnable,
     InvalidProImage,
     LockHeldError,
+    MagicAttachUnavailable,
     NonAutoAttachImageError,
     NonRootUserError,
     RequiredServiceStopsEnable,
@@ -27,6 +28,7 @@
     "EntitlementNotFoundError",
     "InvalidProImage",
     "LockHeldError",
+    "MagicAttachUnavailable",
     "NonAutoAttachImageError",
     "NonRootUserError",
     "UbuntuProError",

uaclient/api/u/pro/attach/magic/initiate/v1.py

@@ -1,4 +1,5 @@
 from uaclient import secret_manager
+from uaclient.api import exceptions
 from uaclient.api.api import APIEndpoint
 from uaclient.api.data_types import AdditionalInfo
 from uaclient.config import UAConfig
@@ -13,10 +14,33 @@
 
 class MagicAttachInitiateResult(DataObject, AdditionalInfo):
     fields = [
-        Field("user_code", StringDataValue),
-        Field("token", StringDataValue),
-        Field("expires", StringDataValue),
-        Field("expires_in", IntDataValue),
+        Field(
+            "user_code",
+            StringDataValue,
+            doc=(
+                "Code the user will see in the UI when confirming the Magic"
+                " Attach"
+            ),
+        ),
+        Field(
+            "token",
+            StringDataValue,
+            doc=(
+                "Magic Token that can be used in either"
+                " `u.pro.attach.magic.revoke.v1`_ or"
+                " `u.pro.attach.magic.wait.v1`_"
+            ),
+        ),
+        Field(
+            "expires",
+            StringDataValue,
+            doc="Timestamp of the Magic Attach process expiration",
+        ),
+        Field(
+            "expires_in",
+            IntDataValue,
+            doc="Seconds before the Magic Attach process expires",
+        ),
     ]
 
     def __init__(
@@ -37,6 +61,10 @@ def initiate() -> MagicAttachInitiateResult:
 
 
 def _initiate(cfg: UAConfig) -> MagicAttachInitiateResult:
+    """
+    This endpoint initiates the Magic Attach flow, retrieving the User Code to
+    confirm the operation and the Token used to proceed.
+    """
     contract = UAContractClient(cfg)
     initiate_resp = contract.new_magic_attach_token()
     secret_manager.secrets.add_secret(initiate_resp["token"])
@@ -55,3 +83,45 @@ def _initiate(cfg: UAConfig) -> MagicAttachInitiateResult:
     fn=_initiate,
     options_cls=None,
 )
+
+_doc = {
+    "introduced_in": "27.11",
+    "example_python": """
+from uaclient.api.u.pro.attach.magic.initiate.v1 import initiate
+
+result = initiate()
+""",
+    "result_cls": MagicAttachInitiateResult,
+    "exceptions": [
+        (
+            exceptions.ConnectivityError,
+            (
+                "Raised if it is not possible to connect to the contracts"
+                " service."
+            ),
+        ),
+        (
+            exceptions.ContractAPIError,
+            (
+                "Raised if there is an unexpected error in the contracts"
+                " service interaction."
+            ),
+        ),
+        (
+            exceptions.MagicAttachUnavailable,
+            (
+                "Raised if the Magic Attach service is busy or unavailable at"
+                " the moment."
+            ),
+        ),
+    ],
+    "example_cli": "pro api u.pro.attach.magic.initiate.v1",
+    "example_json": """
+{
+    "user_code":"<UI_code>",
+    "token":"<magic_token>",
+    "expires": "<yyyy-MM-dd>T<HH:mm:ss>.<TZ>",
+    "expires_in": 600
+}
+""",
+}