Feature/bcss 20437 fit kit gen util markdown and docstring (#54)

<!-- markdownlint-disable-next-line first-line-heading -->
## Description

<!-- Describe your changes in detail. -->
Added docstrings to fit_kit_generation.py and created
FitKitGeneration.md

## Context

<!-- Why is this change required? What problem does it solve? -->
These changes make the code more accessible and readable for anyone
using these utils.

## Type of changes

<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply. -->

- [x] Refactoring (non-breaking change)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would change existing
functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)

## Checklist

<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [x] I am familiar with the [contributing
guidelines](https://github.com/nhs-england-tools/playwright-python-blueprint/blob/main/CONTRIBUTING.md)
- [x] I have followed the code style of the project
- [ ] I have added tests to cover my changes (where appropriate)
- [x] I have updated the documentation accordingly
- [ ] This PR is a result of pair or mob programming

---

## Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others
privacy, we kindly ask you to NOT including [PII (Personal Identifiable
Information) / PID (Personal Identifiable
Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public)
or any other sensitive data in this PR (Pull Request) and the codebase
changes. We will remove any PR that do contain any sensitive
information. We really appreciate your cooperation in this matter.

- [x] I confirm that neither PII/PID nor sensitive data are included in
this PR and the codebase changes.

---------

Co-authored-by: mepr1 <[email protected]>

Author: Andyg79

docs/utility-guides/FitKitGeneration.md

@@ -0,0 +1,68 @@
+# Utility Guide: Fit Kit Generation
+
+The Fit Kit Generation Utility provides methods to generate and manage FIT test kits for testing purposes.
+
+## Table of Contents
+
+- [Utility Guide: Fit Kit Generation](#utility-guide-fit-kit-generation)
+  - [Table of Contents](#table-of-contents)
+  - [Using the Fit Kit Generation Utility](#using-the-fit-kit-generation-utility)
+  - [Required Arguments](#required-arguments)
+  - [Fit Kit Generation Specific Functions](#fit-kit-generation-specific-functions)
+  - [Example Usage](#example-usage)
+
+## Using the Fit Kit Generation Utility
+
+To use the Fit Kit Generation Utility, import the `fit_kit_generation` module, from the `utils` directory, into your test file and call its methods from within your tests, as required. To generate the fit kit IDs, the only method required is `create_fit_id_df`. This will return a `dataframe` with all the transformations already taking place.
+
+## Required Arguments
+
+The methods in this utility require specific arguments. Below is a summary of the required arguments for key methods:
+
+- `generate_kit`: Requires `batch_id` (int) and `kit_type` (str).
+
+## Fit Kit Generation Specific Functions
+
+The Fit Kit Generation Utility includes methods for generating, validating, and managing FIT test kits. These methods are designed to streamline the process of creating test kits for various scenarios. Below are some key functions:
+
+1. **`create_fit_id_df(tk_type_id: int, hub_id: int, no_of_kits: int) -> DataFrame`**
+   Creates a DataFrame containing FIT kit IDs based on the provided parameters.
+   - **Arguments**:
+     - `tk_type_id` (int): The type ID of the test kit.
+     - `hub_id` (int): The hub ID associated with the kits.
+     - `no_of_kits` (int): The number of kits to retrieve.
+   - **Returns**: A pandas DataFrame with the FIT kit IDs.
+
+2. **`calculate_check_digit(kit_id: str) -> str`**
+   Calculates and appends a check digit to the given kit ID.
+   - **Arguments**:
+     - `kit_id` (str): The kit ID to process.
+   - **Returns**: The kit ID with the appended check digit.
+
+3. **`convert_kit_id_to_fit_device_id(kit_id: str) -> str`**
+   Converts a kit ID into a FIT Device ID.
+   - **Arguments**:
+     - `kit_id` (str): The kit ID to convert.
+   - **Returns**: The corresponding FIT Device ID.
+
+## Example Usage
+
+```python
+from utils.fit_kit_generation import create_fit_id_df, calculate_check_digit, convert_kit_id_to_fit_device_id
+
+def example_usage() -> None:
+    # Example inputs
+    tk_type_id = 1
+    hub_id = 101
+    no_of_kits_to_retrieve = 2
+
+    # Calling the fit_kit_df method will do the following:
+      # Step 1: Retrieve and process FIT kit data
+      # Step 2: Calculate a check digit for a single kit ID
+      # Step 3: Convert a kit ID to a FIT Device ID
+
+    fit_kit_df = create_fit_id_df(tk_type_id, hub_id, no_of_kits_to_retrieve)
+    print("Processed FIT Kit DataFrame:")
+    print(fit_kit_df)
+
+example_usage()

utils/fit_kit_generation.py

@@ -8,9 +8,25 @@ def create_fit_id_df(
     tk_type_id: int, hub_id: int, no_of_kits_to_retrieve: int
 ) -> pd.DataFrame:
     """
-    The first step here is to get the relevant test data for compartment 2
-    Then it calculates the check digit for each kit id retrieved
-    Finally it adds the final part on the end (expiry date + random characters)
+    This function retrieves test kit data from the database for the specified compartment (using the 'get_kit_id_from_db' function from 'oracle_specific_functions.py').
+    It then calculates a check digit for each retrieved kit ID and appends it to the kit ID.
+    Finally, it generates a FIT Device ID by appending an expiry date and a fixed suffix to the kit ID.
+
+    For example:
+        Given the following inputs:
+            tk_type_id = 1, hub_id = 101, no_of_kits_to_retrieve = 2
+        The function retrieves two kit IDs from the database, e.g., ["ABC123", "DEF456"].
+        It calculates the check digit for each kit ID, resulting in ["ABC123-K", "DEF456-M"].
+        Then, it generates the FIT Device IDs, e.g., ["ABC123-K122512345/KD00001", "DEF456-M122512345/KD00001"].
+
+    Args:
+        tk_type_id (int): The type ID of the test kit.
+        hub_id (int): The ID of the hub from which to retrieve the kits.
+        no_of_kits_to_retrieve (int): The number of kits to retrieve from the database.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing the processed kit IDs, including the calculated check digit
+        and the final formatted FIT Device ID.
     """
     df = get_kit_id_from_db(tk_type_id, hub_id, no_of_kits_to_retrieve)
     df["fit_device_id"] = df["kitid"].apply(calculate_check_digit)
@@ -20,11 +36,23 @@ def create_fit_id_df(
 
 def calculate_check_digit(kit_id: str) -> str:
     """
-    This function used used to calculate the check digit of a kit ID
-    It calculates the check digit by getting the sum of the location of each character in the kit id
-    Then it divides the sum by 43 and gets the remainder from this
-    It then searches the string "char_string" to find the index of the remainder
-    The character found is then the check digit
+    Calculates the check digit for a given kit ID.
+
+    The check digit is determined by summing the positions of each character in the kit ID
+    within a predefined character set. The remainder of the sum divided by 43 is used to
+    find the corresponding character in the character set, which becomes the check digit.
+
+    For example:
+        Given the kit ID "ABC123", the positions of the characters in the predefined
+        character set are summed. If the total is 123, the remainder when divided by 43
+        is 37. The character at position 37 in the character set is "K". The resulting
+        kit ID with the check digit appended would be "ABC123-K".
+
+    Args:
+        kit_id (str): The kit ID to calculate the check digit for.
+
+    Returns:
+        str: The kit ID with the calculated check digit appended.
     """
     logging.info(f"Calculating check digit for kit id: {kit_id}")
     total = 0
@@ -37,10 +65,17 @@ def calculate_check_digit(kit_id: str) -> str:
 
 def convert_kit_id_to_fit_device_id(kit_id: str) -> str:
     """
-    This is used to add the expiry date to the end of the Kit ID
-    This by setting the month to december
-    And the year is set to 1 year in the future.
-    E.g. if the current date is 06/24 the expiry date will be set to 12/25
+    Converts a Kit ID into a FIT Device ID by appending an expiry date and a fixed suffix.
+
+    The expiry date is calculated by setting the month to December and the year to one year
+    in the future based on the current date. For example, if the current date is June 2024,
+    the expiry date will be set to December 2025.
+
+    Args:
+        kit_id (str): The Kit ID to be converted.
+
+    Returns:
+        str: The generated FIT Device ID in the format "{kit_id}12{next_year}12345/KD00001".
     """
     logging.info(f"Generating FIT Device ID from: {kit_id}")
     today = datetime.now()