Added docstrings and renamed POM files and Classes to include 'Page' (#47)

<!-- markdownlint-disable-next-line first-line-heading -->
## Description
Docstrings added to classes and methods/functions
POM files renamed to include 'Page'
Page Classes refactored to include 'Page'

<!-- Describe your changes in detail. -->

## Context
Following the implementation of our new Contribution Guidance, this
ticket covers updating our existing code to be compliant with our new
guidance.

<!-- Why is this change required? What problem does it solve? -->

## 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.

Author: Andyg79

pages/base_page.py

@@ -3,6 +3,8 @@
 
 
 class BasePage:
+    """Base Page locators and methods for interacting with the page."""
+
     def __init__(self, page: Page):
         self.page = page
         # Homepage/Navigation Bar links
@@ -51,42 +53,54 @@ def __init__(self, page: Page):
         self.main_menu__header = self.page.locator("#ntshPageTitle")
 
     def click_main_menu_link(self) -> None:
+        """Click the Base Page 'Main Menu' link if it is visible."""
         if self.main_menu_link.is_visible():
             self.click(self.main_menu_link)
 
     def click_log_out_link(self) -> None:
+        """Click the Base Page 'Log-out' link."""
         self.click(self.log_out_link)
 
     def click_sub_menu_link(self) -> None:
+        """Click the Base Page 'Show Sub-menu' link."""
         self.click(self.sub_menu_link)
 
     def click_hide_sub_menu_link(self) -> None:
+        """Click the Base Page 'Hide Sub-menu' link."""
         self.click(self.hide_sub_menu_link)
 
     def click_select_org_link(self) -> None:
+        """Click the Base Page 'Select Org' link."""
         self.click(self.select_org_link)
 
     def click_back_button(self) -> None:
+        """Click the Base Page 'Back' button."""
         self.click(self.back_button)
 
     def click_release_notes_link(self) -> None:
+        """Click the Base Page 'Release Notes' link."""
         self.click(self.release_notes_link)
 
     def click_refresh_alerts_link(self) -> None:
+        """Click the Base Page 'Refresh alerts' link."""
         self.click(self.refresh_alerts_link)
 
     def click_user_guide_link(self) -> None:
+        """Click the Base Page 'User guide' link."""
         self.click(self.user_guide_link)
 
     def click_help_link(self) -> None:
+        """Click the Base Page 'Help' link."""
         self.click(self.help_link)
 
     def bowel_cancer_screening_system_header_is_displayed(self) -> None:
+        """Asserts that the Bowel Cancer Screening System header is displayed."""
         expect(self.bowel_cancer_screening_system_header).to_contain_text(
             "Bowel Cancer Screening System"
         )
 
     def main_menu_header_is_displayed(self) -> None:
+        """Asserts that the Main Menu header is displayed."""
         expect(self.main_menu__header).to_contain_text("Main Menu")
 
     def bowel_cancer_screening_page_title_contains_text(self, text: str) -> None:
@@ -106,39 +120,51 @@ def bowel_cancer_screening_page_title_contains_text(self, text: str) -> None:
             expect(self.bowel_cancer_screening_ntsh_page_title).to_contain_text(text)
 
     def go_to_contacts_list_page(self) -> None:
+        """Click the Base Page 'Contacts List' link."""
         self.click(self.contacts_list_page)
 
     def go_to_bowel_scope_page(self) -> None:
+        """Click the Base Page 'Bowel Scope' link."""
         self.click(self.bowel_scope_page)
 
     def go_to_call_and_recall_page(self) -> None:
+        """Click the Base Page 'Call and Recall' link."""
         self.click(self.call_and_recall_page)
 
     def go_to_communications_production_page(self) -> None:
+        """Click the Base Page 'Communications Production' link."""
         self.click(self.communications_production_page)
 
     def go_to_download_page(self) -> None:
+        """Click the Base Page 'Download' link."""
         self.click(self.download_page)
 
     def go_to_fit_test_kits_page(self) -> None:
+        """Click the Base Page 'FIT Test Kits' link."""
         self.click(self.fit_test_kits_page)
 
     def go_to_gfobt_test_kits_page(self) -> None:
+        """Click the Base Page 'gFOBT Test Kits' link."""
         self.click(self.gfobt_test_kits_page)
 
     def go_to_lynch_surveillance_page(self) -> None:
+        """Click the Base Page 'Lynch Surveillance' link."""
         self.click(self.lynch_surveillance_page)
 
     def go_to_organisations_page(self) -> None:
+        """Click the Base Page 'Organisations' link."""
         self.click(self.organisations_page)
 
     def go_to_reports_page(self) -> None:
+        """Click the Base Page 'Reports' link."""
         self.click(self.reports_page)
 
     def go_to_screening_practitioner_appointments_page(self) -> None:
+        """Click the Base Page 'Screening Practitioner Appointments' link."""
         self.click(self.screening_practitioner_appointments_page)
 
     def go_to_screening_subject_search_page(self) -> None:
+        """Click the Base Page 'Screening Subject Search' link."""
         self.click(self.screening_subject_search_page)
 
     def click(self, locator: Locator) -> None:

pages/bowel_scope/bowel_scope_appointments_page.py

@@ -2,12 +2,15 @@
 from pages.base_page import BasePage
 
 
-class BowelScopeAppointments(BasePage):
+class BowelScopeAppointmentsPage(BasePage):
+    """Bowel Scope Appointments page locators, and methods to interact with the page"""
+
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page
         # Bowel Scope Appointments - page locators
         self.page_title = self.page.locator("#ntshPageTitle")
 
     def verify_page_title(self) -> None:
+        """Verifies the page title of the Bowel Scope Appointments page"""
         expect(self.page_title).to_contain_text("Appointment Calendar")

pages/bowel_scope/bowel_scope_page.py

@@ -1,8 +1,10 @@
-from playwright.sync_api import Page, expect, Locator
+from playwright.sync_api import Page
 from pages.base_page import BasePage
 
 
-class BowelScope(BasePage):
+class BowelScopePage(BasePage):
+    """Bowel Scope page locators, and methods to interact with the page"""
+
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page
@@ -12,4 +14,5 @@ def __init__(self, page: Page):
         )
 
     def go_to_view_bowel_scope_appointments_page(self) -> None:
+        """Clicks the link to navigate to the Bowel Scope Appointments page"""
         self.click(self.view_bowel_scope_appointments_page)

pages/call_and_recall/age_extension_rollout_plans_page.py

@@ -2,14 +2,17 @@
 from pages.base_page import BasePage
 
 
-class AgeExtensionRolloutPlans(BasePage):
+class AgeExtensionRolloutPlansPage(BasePage):
+    """Age Extension Rollout Plans page locators, and methods to interact with the page"""
+
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page
         # Age Extension Rollout Plans - page locators
         self.age_extension_rollout_plans_title = self.page.locator("#page-title")
 
     def verify_age_extension_rollout_plans_title(self) -> None:
+        """Verifies the page title of the Age Extension Rollout Plans page"""
         expect(self.age_extension_rollout_plans_title).to_contain_text(
             "Age Extension Rollout Plans"
         )

pages/call_and_recall/call_and_recall_page.py

@@ -2,7 +2,9 @@
 from pages.base_page import BasePage
 
 
-class CallAndRecall(BasePage):
+class CallAndRecallPage(BasePage):
+    """Call and Recall page locators, and methods to interact with the page"""
+
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page
@@ -24,16 +26,21 @@ def __init__(self, page: Page):
         )
 
     def go_to_planning_and_monitoring_page(self) -> None:
+        """Clicks the link to navigate to the Planning and Monitoring page"""
         self.click(self.planning_and_monitoring_page)
 
     def go_to_generate_invitations_page(self) -> None:
+        """Clicks the link to navigate to the Generate Invitations page"""
         self.click(self.generate_invitations_page)
 
     def go_to_invitation_generation_progress_page(self) -> None:
+        """Clicks the link to navigate to the Invitation Generation Progress page"""
         self.click(self.invitation_generation_progress_page)
 
     def go_to_non_invitation_days_page(self) -> None:
+        """Clicks the link to navigate to the Non Invitation Days page"""
         self.click(self.non_invitation_days_page)
 
     def go_to_age_extension_rollout_plans_page(self) -> None:
+        """Clicks the link to navigate to the Age Extension Rollout Plans page"""
         self.click(self.age_extension_rollout_plans_page)

pages/call_and_recall/create_a_plan_page.py

@@ -2,7 +2,9 @@
 from pages.base_page import BasePage
 
 
-class CreateAPlan(BasePage):
+class CreateAPlanPage(BasePage):
+    """Create a Plan page locators and methods to interact with the page"""
+
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page
@@ -24,28 +26,37 @@ def __init__(self, page: Page):
         self.create_a_plan_title = self.page.locator("#page-title")
 
     def click_set_all_button(self) -> None:
+        """Clicks the Set all button to set all values"""
         self.click(self.set_all_button)
 
     def fill_daily_invitation_rate_field(self, value: str) -> None:
+        """Fills the daily invitation rate field with the given value"""
         self.daily_invitation_rate_field.fill(value)
 
     def fill_weekly_invitation_rate_field(self, value) -> None:
+        """Fills the weekly invitation rate field with the given value"""
         self.weekly_invitation_rate_field.fill(value)
 
     def click_update_button(self) -> None:
+        """Clicks the Update button to save any changes"""
         self.click(self.update_button)
 
     def click_confirm_button(self) -> None:
+        """Clicks the Confirm button"""
         self.click(self.confirm_button)
 
     def click_save_button(self) -> None:
+        """Clicks the Save button"""
         self.click(self.save_button)
 
     def fill_note_field(self, value) -> None:
+        """Fills the note field with the given value"""
         self.note_field.fill(value)
 
     def click_save_note_button(self) -> None:
+        """Clicks the Save note button"""
         self.click(self.save_note_button)
 
     def verify_create_a_plan_title(self) -> None:
+        """Verifies the Create a Plan page title"""
         expect(self.create_a_plan_title).to_contain_text("View a plan")

pages/call_and_recall/generate_invitations_page.py

@@ -4,7 +4,9 @@
 import logging
 
 
-class GenerateInvitations(BasePage):
+class GenerateInvitationsPage(BasePage):
+    """Generate Invitations page locators, and methods to interact with the page"""
+
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page
@@ -19,15 +21,19 @@ def __init__(self, page: Page):
         self.generate_invitations_title = self.page.locator("#ntshPageTitle")
 
     def click_generate_invitations_button(self) -> None:
+        """This function is used to click the Generate Invitations button."""
         self.click(self.generate_invitations_button)
 
     def click_refresh_button(self) -> None:
+        """This function is used to click the Refresh button."""
         self.click(self.refresh_button)
 
     def verify_generate_invitations_title(self) -> None:
+        """This function is used to verify the Generate Invitations page title."""
         expect(self.generate_invitations_title).to_contain_text("Generate Invitations")
 
     def verify_invitation_generation_progress_title(self) -> None:
+        """This function is used to verify the Invitation Generation Progress page title."""
         expect(self.generate_invitations_title).to_contain_text(
             "Invitation Generation Progress"
         )

pages/call_and_recall/invitations_monitoring_page.py

@@ -2,7 +2,9 @@
 from pages.base_page import BasePage
 
 
-class InvitationsMonitoring(BasePage):
+class InvitationsMonitoringPage(BasePage):
+    """Invitations Monitoring page locators, and methods to interact with the page"""
+
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page

pages/call_and_recall/invitations_plans_page.py

@@ -2,7 +2,9 @@
 from pages.base_page import BasePage
 
 
-class InvitationsPlans(BasePage):
+class InvitationsPlansPage(BasePage):
+    """Invitations Plans page locators, and methods to interact with the page"""
+
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page
@@ -16,7 +18,9 @@ def __init__(self, page: Page):
         )
 
     def go_to_create_a_plan_page(self) -> None:
+        """Clicks the Create a Plan button to navigate to the Create a Plan page"""
         self.click(self.create_a_plan)
 
     def go_to_first_available_plan(self) -> None:
+        """Clicks the first available plan to navigate to the Create a Plan page"""
         self.click(self.first_available_plan)

pages/call_and_recall/non_invitations_days_page.py

@@ -2,12 +2,15 @@
 from pages.base_page import BasePage
 
 
-class NonInvitationDays(BasePage):
+class NonInvitationDaysPage(BasePage):
+    """Non Invitation Days page locators, and methods to interact with the page"""
+
     def __init__(self, page: Page):
         super().__init__(page)
         self.page = page
         # Non Invitation Days - page locators
         self.non_invitations_days_title = self.page.locator("#ntshPageTitle")
 
     def verify_non_invitation_days_tile(self) -> None:
+        """Verifies the page title of the Non Invitation Days page"""
         expect(self.non_invitations_days_title).to_contain_text("Non-Invitation Days")