tftp: add docs

Signed-off-by: Benny Zlotnik <[email protected]>

Author: bennyz

docs/source/api-reference/drivers/index.md

@@ -10,6 +10,6 @@ Drivers packages from the [drivers](https://github.com/jumpstarter-dev/jumpstart
 can.md
 pyserial.md
 sdwire.md
+tftp.md
 ustreamer.md
 yepkit.md
-```

docs/source/api-reference/drivers/tftp.md

@@ -0,0 +1,68 @@
+# TFTP Driver
+
+**driver**: `jumpstarter_driver_tftp.driver.Tftp`
+
+The TFTP driver provides a read-only TFTP server that can be used to serve files.
+
+## Driver Configuration
+```yaml
+export:
+  tftp:
+    type: jumpstarter_driver_tftp.driver.Tftp
+    config:
+      root_dir: /var/lib/tftpboot  # Directory to serve files from
+      host: 192.168.1.100          # Host IP to bind to (optional)
+      port: 69                     # Port to listen on (optional)
+```
+
+### Config parameters
+
+| Parameter | Description | Type | Required | Default |
+|-----------|-------------|------|----------|---------|
+| root_dir | Root directory for the TFTP server | str | no | "/var/lib/tftpboot" |
+| host | IP address to bind the server to | str | no | auto-detect |
+| port | Port number to listen on | int | no | 69 |
+
+## TftpClient API
+
+```{eval-rst}
+.. autoclass:: jumpstarter_driver_tftp.driver.Tftp
+   :members:
+   :show-inheritance:
+```
+
+## Exception Classes
+
+```{eval-rst}
+.. autoclass:: jumpstarter_driver_tftp.driver.TftpError
+   :members:
+   :show-inheritance:
+
+.. autoclass:: jumpstarter_driver_tftp.driver.ServerNotRunning
+   :members:
+   :show-inheritance:
+
+.. autoclass:: jumpstarter_driver_tftp.driver.FileNotFound
+   :members:
+   :show-inheritance:
+```
+
+## Examples
+
+### Starting a TFTP server
+```python
+from jumpstarter_driver_tftp import Tftp
+
+# Create and start a TFTP server
+tftp = Tftp(root_dir="/tftpboot", host="192.168.1.100")
+tftp.start()
+
+# Upload a file
+tftp.put_file("kernel.img", file_stream, checksum)
+
+# List available files
+files = tftp.list_files()
+
+# Stop the server
+tftp.stop()
+```

packages/jumpstarter-driver-tftp/jumpstarter_driver_tftp/driver.py

@@ -29,7 +29,30 @@ class FileNotFound(TftpError):
 
 @dataclass(kw_only=True)
 class Tftp(Driver):
-    """TFTP Server driver for Jumpstarter"""
+    """TFTP Server driver for Jumpstarter
+
+    This driver implements a TFTP read-only server.
+
+    Attributes:
+        root_dir (str): Root directory for the TFTP server. Defaults to "/var/lib/tftpboot"
+        host (str): IP address to bind the server to. If empty, will use the default route interface
+        port (int): Port number to listen on. Defaults to 69 (standard TFTP port)
+
+    Example:
+        >>> from jumpstarter_driver_tftp import Tftp
+        >>> # Create and start a TFTP server
+        >>> tftp = Tftp(root_dir="/tftpboot", host="192.168.1.100")
+        >>> tftp.start()
+        >>>
+        >>> # Upload a file
+        >>> tftp.put_file("kernel.img", file_stream, checksum)
+        >>>
+        >>> # List available files
+        >>> files = tftp.list_files()
+        >>>
+        >>> # Stop the server
+        >>> tftp.stop()
+    """
 
     root_dir: str = "/var/lib/tftpboot"
     host: str = field(default='')
@@ -97,6 +120,14 @@ async def _wait_for_shutdown(self):
 
     @export
     def start(self):
+        """Start the TFTP server.
+
+        The server will start listening for incoming TFTP requests on the configured
+        host and port. If the server is already running, a warning will be logged.
+
+        Raises:
+            TftpError: If the server fails to start or times out during initialization
+        """
         if self.server_thread is not None and self.server_thread.is_alive():
             self.logger.warning("TFTP server is already running")
             return
@@ -116,6 +147,11 @@ def start(self):
 
     @export
     def stop(self):
+        """Stop the TFTP server.
+
+        Initiates a graceful shutdown of the server and waits for all active transfers
+        to complete. If the server is not running, a warning will be logged.
+        """
         if self.server_thread is None or not self.server_thread.is_alive():
             self.logger.warning("stop called - TFTP server is not running")
             return
@@ -131,10 +167,28 @@ def stop(self):
 
     @export
     def list_files(self) -> list[str]:
+        """List all files available in the TFTP server root directory.
+
+        Returns:
+            list[str]: A list of filenames present in the root directory
+        """
         return os.listdir(self.root_dir)
 
     @export
     async def put_file(self, filename: str, src_stream, client_checksum: str):
+        """Upload a file to the TFTP server.
+
+        Args:
+            filename (str): Name of the file to create
+            src_stream: Source stream to read the file data from
+            client_checksum (str): SHA256 checksum of the file for verification
+
+        Returns:
+            str: The filename that was uploaded
+
+        Raises:
+            TftpError: If the file upload fails or path validation fails
+        """
         file_path = os.path.join(self.root_dir, filename)
 
         try:
@@ -152,6 +206,18 @@ async def put_file(self, filename: str, src_stream, client_checksum: str):
 
     @export
     def delete_file(self, filename: str):
+        """Delete a file from the TFTP server.
+
+        Args:
+            filename (str): Name of the file to delete
+
+        Returns:
+            str: The filename that was deleted
+
+        Raises:
+            FileNotFound: If the specified file does not exist
+            TftpError: If the deletion operation fails
+        """
         file_path = os.path.join(self.root_dir, filename)
 
         if not os.path.exists(file_path):
@@ -165,6 +231,15 @@ def delete_file(self, filename: str):
 
     @export
     def check_file_checksum(self, filename: str, client_checksum: str) -> bool:
+        """Check if a file matches the expected checksum.
+
+        Args:
+            filename (str): Name of the file to check
+            client_checksum (str): Expected SHA256 checksum
+
+        Returns:
+            bool: True if the file exists and matches the checksum, False otherwise
+        """
         file_path = os.path.join(self.root_dir, filename)
         self.logger.debug(f"checking checksum for file: {filename}")
         self.logger.debug(f"file path: {file_path}")
@@ -181,10 +256,20 @@ def check_file_checksum(self, filename: str, client_checksum: str) -> bool:
 
     @export
     def get_host(self) -> str:
+        """Get the host address the server is bound to.
+
+        Returns:
+            str: The IP address or hostname
+        """
         return self.host
 
     @export
     def get_port(self) -> int:
+        """Get the port number the server is listening on.
+
+        Returns:
+            int: The port number
+        """
         return self.port
 
     def close(self):