chore: add reusable generate reference docs action

[OmarAlJarrah]

Situation

In this pull request, we aim to automate the deployment of reference documentation for our SDK. This is part of our ongoing effort to improve the developer experience by ensuring that the latest documentation is always available and up-to-date.

Task

We need to create a GitHub Actions workflow that will generate and deploy reference documentation whenever a new version of the SDK is released. The workflow should support both Gradle and Maven build systems.

Action

1. Setup GitHub Actions Workflow: We created a new GitHub Actions workflow file named generate-ref-docs.yaml.
2. Configure Workflow Inputs: The workflow accepts inputs for the build system (gradle or maven) and a GitHub Personal Access Token (PAT) for authentication.
3. Setup Java Environment: The workflow sets up a Java environment using Corretto JDK 21.
4. Generate Documentation: Depending on the build system specified, the workflow generates the documentation using Dokka for Gradle or Maven.
5. Version Management: The workflow checks the version of the newly generated documentation and ensures it does not conflict with existing versions.
6. Deploy Documentation: The workflow moves the newly generated documentation to the gh-pages branch and creates a pull request for review.

Testing

The workflow was tested manually by triggering it with both Gradle and Maven build systems. We verified that the documentation was generated and deployed correctly without any version conflicts.

Results

The new workflow automates the deployment of reference documentation, ensuring that the latest version is always available. This reduces manual effort and minimizes the risk of outdated documentation being published.

Notes

Should be followed up by:

• chore: migrate to reusable ref docs gh action lodging-connectivity-java-sdk#152
• chore: migrate to reusable ref docs gh action rapid-java-sdk#260

[mohnoor94]

Can you please if choice is supported for this case? if not, let's convert the input to lower case so we don't care about similar inputs like: maven, Maven, and MAVEN, etc...