documentation fixes

Author: davethepunkyone

docs/utility-guides/JiraConfluenceUtil.md

@@ -13,14 +13,14 @@ The `JiraConfluenceUtil` utility provides methods for interacting with Jira and
     - [Required Environment Variables](#required-environment-variables)
     - [Initialise the class](#initialise-the-class)
   - [Public Methods](#public-methods)
-    - [get\_issue\_data](#get_issue_data)
-    - [get\_issue\_summary\_in\_issue\_data](#get_issue_summary_in_issue_data)
-    - [check\_attachment\_exists\_in\_issue\_data](#check_attachment_exists_in_issue_data)
-    - [is\_valid\_jira\_reference](#is_valid_jira_reference)
-    - [determine\_jira\_reference\_local](#determine_jira_reference_local)
-    - [get\_environment\_metadata\_if\_available](#get_environment_metadata_if_available)
-    - [is\_file\_is\_less\_than\_jira\_file\_limit](#is_file_is_less_than_jira_file_limit)
-    - [upload\_test\_results\_dir\_to\_jira](#upload_test_results_dir_to_jira)
+    - [`get_issue_data`](#get_issue_data)
+    - [`get_issue_summary_in_issue_data`](#get_issue_summary_in_issue_data)
+    - [`check_attachment_exists_in_issue_data`](#check_attachment_exists_in_issue_data)
+    - [`is_valid_jira_reference`](#is_valid_jira_reference)
+    - [`determine_jira_reference_local`](#determine_jira_reference_local)
+    - [`get_environment_metadata_if_available`](#get_environment_metadata_if_available)
+    - [`is_file_is_less_than_jira_file_limit`](#is_file_is_less_than_jira_file_limit)
+    - [`upload_test_results_dir_to_jira`](#upload_test_results_dir_to_jira)
   - [Example Usage](#example-usage)
 
 ## Using the JiraConfluenceUtil class
@@ -60,7 +60,7 @@ util = JiraConfluenceUtil(results_dir="path/to/results")
 
 ## Public Methods
 
-### get_issue_data
+### `get_issue_data`
 
 ```python
 get_issue_data(ticket_id: str) -> dict | None
@@ -70,7 +70,7 @@ Checks if a Jira issue exists and returns its data as a dictionary, or `None` if
 
 ---
 
-### get_issue_summary_in_issue_data
+### `get_issue_summary_in_issue_data`
 
 ```python
 get_issue_summary_in_issue_data(issue_data: dict) -> str | None
@@ -80,7 +80,7 @@ Returns a summary string for the given Jira issue data in the format "[Ticket]:
 
 ---
 
-### check_attachment_exists_in_issue_data
+### `check_attachment_exists_in_issue_data`
 
 ```python
 check_attachment_exists_in_issue_data(issue_data: dict, filename: str) -> bool
@@ -90,7 +90,7 @@ Checks if a Jira issue already has an attachment with the specified filename.
 
 ---
 
-### is_valid_jira_reference
+### `is_valid_jira_reference`
 
 ```python
 is_valid_jira_reference(ticket_id: str) -> bool
@@ -100,7 +100,7 @@ Validates that the Jira ticket reference is in the expected format (e.g., `SCM-1
 
 ---
 
-### determine_jira_reference_local
+### `determine_jira_reference_local`
 
 ```python
 determine_jira_reference_local() -> str
@@ -118,7 +118,7 @@ This is currently configured to search for the format `feature/[Jira Reference]`
 
 ---
 
-### get_environment_metadata_if_available
+### `get_environment_metadata_if_available`
 
 ```python
 get_environment_metadata_if_available() -> str
@@ -133,7 +133,7 @@ designed to be overwritten.
 
 ---
 
-### is_file_is_less_than_jira_file_limit
+### `is_file_is_less_than_jira_file_limit`
 
 ```python
 is_file_is_less_than_jira_file_limit(file_path: Path) -> bool
@@ -143,7 +143,7 @@ Checks if the file size is below the Jira upload limit (10MB).
 
 ---
 
-### upload_test_results_dir_to_jira
+### `upload_test_results_dir_to_jira`
 
 ```python
 upload_test_results_dir_to_jira(

jira_upload.py

@@ -4,27 +4,27 @@
 CI/CD operations.
 
 The following environment variables need to be set (in local.env if running locally) before this can upload any files:
- - JIRA_URL: The Jira instance to upload to.
- - JIRA_PROJECT_KEY: The Jira project key that should be uploaded to.
- - JIRA_API_KEY: The API key to use to complete actions. Locally you should generate your own key, and use a bot in a pipeline/workflow.
+    - JIRA_URL: The Jira instance to upload to.
+    - JIRA_PROJECT_KEY: The Jira project key that should be uploaded to.
+    - JIRA_API_KEY: The API key to use to complete actions. Locally you should generate your own key, and use a bot in a pipeline/workflow.
 
 The following environment variables are optional:
- - JIRA_TICKET_REFERENCE: The Jira ticket to push to if set. If not, will attempt to derive the value from the git branch.
+    - JIRA_TICKET_REFERENCE: The Jira ticket to push to if set. If not, will attempt to derive the value from the git branch.
 
 The script itself can be executed using the following command:
     python jira_upload.py
 
 The following arguments are supported in addition:
- --jira-ref <Jira Reference> = The Jira ticket to upload to. Will take precedence over auto-deriving from branch name and the set environment variable.
- --results-dir <Directory> = The directory to point to. If not set, points to test-results/ in this directory.
- --no-html = Don't include HTML files in the upload.
- --no-trace = Don't include Trace files (.zip) in the upload.
- --no-csv = Don't include CSV files in the upload.
- --no-screenshots = Don't include screenshots (.png) in the upload.
- --no-comment = Don't add a Jira comment highlighting the results.
- --no-env-data = Don't include environment data in the Jira comment.
- --overwrite-files = If a filename exists on the ticket that matches those in the results directory, overwrite them.
- --auto-confirm = Will not ask if you want to proceed if set, and will assume that yes has been pressed.
+    --jira-ref <Jira Reference> = The Jira ticket to upload to. Will take precedence over auto-deriving from branch name and the set environment variable.
+    --results-dir <Directory> = The directory to point to. If not set, points to test-results/ in this directory.
+    --no-html = Don't include HTML files in the upload.
+    --no-trace = Don't include Trace files (.zip) in the upload.
+    --no-csv = Don't include CSV files in the upload.
+    --no-screenshots = Don't include screenshots (.png) in the upload.
+    --no-comment = Don't add a Jira comment highlighting the results.
+    --no-env-data = Don't include environment data in the Jira comment.
+    --overwrite-files = If a filename exists on the ticket that matches those in the results directory, overwrite them.
+    --auto-confirm = Will not ask if you want to proceed if set, and will assume that yes has been pressed.
 """
 
 import argparse
@@ -38,10 +38,18 @@ def upload_jira_files(args: argparse.Namespace) -> None:
     Jira.
     """
     try:
-        jira_instance = JiraConfluenceUtil() if args.results_dir is None else JiraConfluenceUtil(results_dir=args.results_dir)
+        jira_instance = (
+            JiraConfluenceUtil()
+            if args.results_dir is None
+            else JiraConfluenceUtil(results_dir=args.results_dir)
+        )
 
         if args.jira_ref is not None:
-            jira_ref = args.jira_ref if jira_instance.is_valid_jira_reference(args.jira_ref) else ""
+            jira_ref = (
+                args.jira_ref
+                if jira_instance.is_valid_jira_reference(args.jira_ref)
+                else ""
+            )
         else:
             jira_ref = jira_instance.determine_jira_reference_local()
 
@@ -57,7 +65,7 @@ def upload_jira_files(args: argparse.Namespace) -> None:
             include_csv=not args.no_csv,
             include_env_metadata=not args.no_env_data,
             add_comment=not args.no_comment,
-            automatically_accept=args.auto_confirm
+            automatically_accept=args.auto_confirm,
         )
     except Exception as e:
         print("An error has been encountered so exiting upload process")
@@ -69,15 +77,39 @@ def upload_jira_files(args: argparse.Namespace) -> None:
     parser = argparse.ArgumentParser(
         description="Upload test results from the test-results directory."
     )
-    parser.add_argument("--jira-ref", type=str, help="Specify the Jira reference to upload to")
-    parser.add_argument("--results-dir", type=str, help="Specify the results directory to upload from")
-    parser.add_argument("--no-html", action="store_true", help="Don't include HTML files in upload")
-    parser.add_argument("--no-trace", action="store_true", help="Don't include trace files")
+    parser.add_argument(
+        "--jira-ref", type=str, help="Specify the Jira reference to upload to"
+    )
+    parser.add_argument(
+        "--results-dir", type=str, help="Specify the results directory to upload from"
+    )
+    parser.add_argument(
+        "--no-html", action="store_true", help="Don't include HTML files in upload"
+    )
+    parser.add_argument(
+        "--no-trace", action="store_true", help="Don't include trace files"
+    )
     parser.add_argument("--no-csv", action="store_true", help="Don't include CSV files")
-    parser.add_argument("--no-screenshots", action="store_true", help="Don't include screenshots")
-    parser.add_argument("--no-comment", action="store_true", help="Don't include a comment")
-    parser.add_argument("--no-env-data", action="store_true", help="Don't include environment metadata in comment")
-    parser.add_argument("--overwrite-files", action="store_true", help="If files are already on the Jira ticket with the same name, overwrite them with this file.")
-    parser.add_argument("--auto-confirm", action="store_true", help="Don't prompt to confirm actions before proceeding")
+    parser.add_argument(
+        "--no-screenshots", action="store_true", help="Don't include screenshots"
+    )
+    parser.add_argument(
+        "--no-comment", action="store_true", help="Don't include a comment"
+    )
+    parser.add_argument(
+        "--no-env-data",
+        action="store_true",
+        help="Don't include environment metadata in comment",
+    )
+    parser.add_argument(
+        "--overwrite-files",
+        action="store_true",
+        help="If files are already on the Jira ticket with the same name, overwrite them with this file.",
+    )
+    parser.add_argument(
+        "--auto-confirm",
+        action="store_true",
+        help="Don't prompt to confirm actions before proceeding",
+    )
     args = parser.parse_args()
     upload_jira_files(args)

scripts/config/vale/styles/config/vocabularies/words/accept.txt

@@ -6,6 +6,7 @@ Dependabot
 Gitleaks
 Grype
 idempotence
+Jira
 OAuth
 Octokit
 onboarding