Merge pull request 'Docs: add missing documentation to api functions' (#4243) from api-cleanup into main

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4243

pkgs/clan-cli/clan_lib/machines/actions.py

@@ -54,6 +54,19 @@ def list_machines(
 
 @API.register
 def get_machine(flake: Flake, name: str) -> InventoryMachine:
+    """
+    Retrieve a machine's inventory details by name from the given flake.
+
+    Args:
+        flake (Flake): The flake object representing the configuration source.
+        name (str): The name of the machine to retrieve from the inventory.
+
+    Returns:
+        InventoryMachine: An instance representing the machine's inventory details.
+
+    Raises:
+        ClanError: If the machine with the specified name is not found in the inventory.
+    """
     inventory_store = InventoryStore(flake=flake)
     inventory = inventory_store.read()
 

pkgs/clan-cli/clan_lib/machines/delete.py

@@ -19,6 +19,13 @@ log = logging.getLogger(__name__)
 
 @API.register
 def delete_machine(machine: Machine) -> None:
+    """Delete a machine from the clan's inventory and remove its associated files.
+    Args:
+        machine: The Machine instance to be deleted.
+    Raises:
+        ClanError: If the machine does not exist in the inventory or if there are issues with
+            removing its files.
+    """
     inventory_store = InventoryStore(machine.flake)
     try:
         inventory_store.delete(

pkgs/clan-cli/clan_lib/machines/install.py

@@ -40,6 +40,16 @@ class InstallOptions:
 
 @API.register
 def run_machine_install(opts: InstallOptions, target_host: Remote) -> None:
+    """Install a machine using nixos-anywhere.
+    Args:
+        opts: InstallOptions containing the machine to install, kexec option, debug mode,
+            no-reboot option, phases, build-on option, hardware config update, password,
+            identity file, and use_tor flag.
+        target_host: Remote object representing the target host for installation.
+    Raises:
+        ClanError: If the machine is not found in the inventory or if there are issues with
+            generating facts or variables.
+    """
     machine = opts.machine
 
     machine.debug(f"installing {machine.name}")

pkgs/clan-cli/clan_lib/machines/list.py

@@ -52,8 +52,22 @@ def extract_header(c: str) -> str:
     return "\n".join(header_lines)
 
 
+# TODO: Remove this function
+# Split out the disko schema extraction into a separate function
+# get machine returns the machine already
 @API.register
 def get_machine_details(machine: Machine) -> MachineDetails:
+    """Retrieve detailed information about a machine, including its inventory,
+    hardware configuration, and disk schema if available.
+    Args:
+        machine (Machine): The machine instance for which details are to be retrieved.
+    Returns:
+        MachineDetails: An instance containing the machine's inventory, hardware configuration,
+        and disk schema.
+    Raises:
+        ClanError: If the machine's inventory cannot be found or if there are issues with the
+        hardware configuration or disk schema extraction.
+    """
     machine_inv = get_machine(machine.flake, machine.name)
     hw_config = HardwareConfig.detect_type(machine)
 

pkgs/clan-cli/clan_lib/machines/update.py

@@ -106,6 +106,16 @@ def upload_sources(machine: Machine, ssh: Remote) -> str:
 def run_machine_deploy(
     machine: Machine, target_host: Remote, build_host: Remote | None
 ) -> None:
+    """Update an existing machine using nixos-rebuild or darwin-rebuild.
+    Args:
+        machine: The Machine instance to deploy.
+        target_host: Remote object representing the target host for deployment.
+        build_host: Optional Remote object representing the build host.
+    Raises:
+        ClanError: If the machine is not found in the inventory or if there are issues with
+            generating facts or variables.
+    """
+
     with ExitStack() as stack:
         target_host = stack.enter_context(target_host.ssh_control_master())