Feature/bcss 20625 datetimeutils markdown updates (#88)

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

<!-- Describe your changes in detail. -->
Altering the markdown document to address review comments.

## Context

<!-- Why is this change required? What problem does it solve? -->
Makes the utility easier to understand how and when to use the different
methods.

## 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)
- [ ] 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.

Author: adrianoaru-nhs

docs/utility-guides/DateTimeUtility.md

@@ -1,22 +1,131 @@
 # Utility Guide: Date Time Utility
 
-The Date Time Utility can be used to manipulate dates and times for various purposes,
-such as asserting timestamp values, changing the format of a date, or returning the day of the week for a given date.
+The Date Time Utility provides a set of helper functions for manipulating dates and times in your tests.
+You can use it to assert timestamp values, change the format of a date, calculate date differences, add or subtract time, and more.
+
+## Table of Contents
+
+- [Utility Guide: Date Time Utility](#utility-guide-date-time-utility)
+  - [Table of Contents](#table-of-contents)
+  - [Using the Date Time Utility](#using-the-date-time-utility)
+  - [Main Features](#main-features)
+  - [Example Usage](#example-usage)
+  - [Method Reference](#method-reference)
+    - [`current_datetime(format_date: str = "%d/%m/%Y %H:%M") -> str`](#current_datetimeformat_date-str--dmy-hm---str)
+    - [`format_date(date: datetime, format_date: str = "%d/%m/%Y") -> str`](#format_datedate-datetime-format_date-str--dmy---str)
+    - [`add_days(date: datetime, days: float) -> datetime`](#add_daysdate-datetime-days-float---datetime)
+    - [`get_day_of_week_for_today(date: datetime) -> str`](#get_day_of_week_for_todaydate-datetime---str)
+    - [`get_a_day_of_week(date: datetime) -> str`](#get_a_day_of_weekdate-datetime---str)
+    - [`report_timestamp_date_format() -> str`](#report_timestamp_date_format---str)
+    - [`fobt_kits_logged_but_not_read_report_timestamp_date_format() -> str`](#fobt_kits_logged_but_not_read_report_timestamp_date_format---str)
+    - [`screening_practitioner_appointments_report_timestamp_date_format() -> str`](#screening_practitioner_appointments_report_timestamp_date_format---str)
+    - [`month_string_to_number(string: str) -> int`](#month_string_to_numberstring-str---int)
 
 ## Using the Date Time Utility
 
-To use the Date Time Utility, import the 'DateTimeUtils' class into your test file and then call the DateTimeUtils
-functions from within your tests, as required.
+To use the Date Time Utility, import the `DateTimeUtils` class from `utils.date_time_utils` into your test file and call its methods as needed.
+
+```python
+from utils.date_time_utils import DateTimeUtils
+```
+
+## Main Features
+
+- Get the current date/time in various formats
+- Format dates to different string representations
+- Add or subtract days from a date
+- Get the day of the week for a given date
+- Get formatted timestamps for different report types
+- Convert a month name string to its corresponding number
+
+---
+
+## Example Usage
+
+```python
+from utils.date_time_utils import DateTimeUtils
+from datetime import datetime
+
+# Get the current date and time as a string
+now_str = DateTimeUtils.current_datetime()
+print(now_str)  # e.g. '28/05/2025 14:30'
+
+# Format a datetime object as 'dd/mm/yyyy'
+formatted = DateTimeUtils.format_date(datetime(2025, 1, 16))
+print(formatted)  # '16/01/2025'
+
+# Add 5 days to a date
+future_date = DateTimeUtils.add_days(datetime(2025, 1, 16), 5)
+print(future_date)  # datetime object for 21/01/2025
+
+# Get the day of the week for a date
+weekday = DateTimeUtils.get_day_of_week_for_today(datetime(2025, 1, 16))
+print(weekday)  # 'Thursday'
+
+# Get the day of the week (alias method)
+weekday2 = DateTimeUtils.get_a_day_of_week(datetime(2025, 1, 16))
+print(weekday2)  # 'Thursday'
+
+# Get the current timestamp in report format
+report_timestamp = DateTimeUtils.report_timestamp_date_format()
+print(report_timestamp)  # e.g. '28/05/2025 at 14:30:00'
+
+# Get the current timestamp in FOBT kits report format
+fobt_timestamp = DateTimeUtils.fobt_kits_logged_but_not_read_report_timestamp_date_format()
+print(fobt_timestamp)  # e.g. '28 May 2025 14:30:00'
+
+# Get the current timestamp in screening practitioner appointments report format
+spa_timestamp = DateTimeUtils.screening_practitioner_appointments_report_timestamp_date_format()
+print(spa_timestamp)  # e.g. '28.05.2025 at 14:30:00'
+
+# Convert a month name to its number
+month_num = DateTimeUtils().month_string_to_number("February")
+print(month_num)  # 2
+
+month_num_short = DateTimeUtils().month_string_to_number("Sep")
+print(month_num_short)  # 9
+```
+
+---
+
+## Method Reference
+
+### `current_datetime(format_date: str = "%d/%m/%Y %H:%M") -> str`
+
+Returns the current date as a string in the specified format.
+
+### `format_date(date: datetime, format_date: str = "%d/%m/%Y") -> str`
+
+Formats a given `datetime` object as a string.
+
+### `add_days(date: datetime, days: float) -> datetime`
+
+Adds a specified number of days to a given date.
+
+### `get_day_of_week_for_today(date: datetime) -> str`
+
+Returns the day of the week for the given date.
+
+### `get_a_day_of_week(date: datetime) -> str`
+
+Alias for `get_day_of_week_for_today`.
+
+### `report_timestamp_date_format() -> str`
+
+Returns the current date and time in the format `'dd/mm/yyyy at hh:mm:ss'`.
+
+### `fobt_kits_logged_but_not_read_report_timestamp_date_format() -> str`
+
+Returns the current date and time in the format `'dd Mon yyyy hh:mm:ss'`.
+
+### `screening_practitioner_appointments_report_timestamp_date_format() -> str`
 
-## Required arguments
+Returns the current date and time in the format `'dd.mm.yyyy at hh:mm:ss'`.
 
-The functions in this class require different arguments, including `datetime`, `str`, and `float`.
-Look at the docstrings for each function to see what arguments are required.
-The docstrings also specify when arguments are optional, and what the default values are when no argument is provided.
+### `month_string_to_number(string: str) -> int`
 
-## Example usage
+Converts a month name (full or short, case-insensitive) to its corresponding number (1-12).
 
-    from tests_utils.date_time_utils import DateTimeUtils
+---
 
-        def test_date_format(page: Page) -> None:
-        expect(page.locator("#date")).to_contain_text(DateTimeUtils.current_datetime())
+Refer to the source code and function docstrings in `utils/date_time_utils.py` for more details and any additional helper methods.