create documentation pipeline to update and maintain control docs

PR Type:

Enhancement

PR Description:

This PR introduces an automated documentation generation and synchronization pipeline for the control library. The main changes include:

A modified upload-readme.py script to generate static markdown files for each control.
A new sync.yml GitHub action that triggers on changes to the docs/controls directory and opens a pull request to sync the changes to the kubescape.io website repository.
The create-release.yaml workflow has been updated to execute the documentation generator script with every release.
A new mk-generator.py script has been added to generate the markdown files (not shown in the diff due to token budget limitations).

PR Main Files Walkthrough:

files:

- `scripts/upload-readme.py`: The script has been heavily modified to generate static markdown files for each control. This includes adding detailed comments to the functions, and modifying the `create_md_for_control` function to generate markdown text for each control. - `.github/workflows/sync.yml`: This new file defines a GitHub action that triggers on changes to the `docs/controls` directory. It uses the `BetaHuhn/repo-file-sync-action@v1` action to open a pull request that syncs the changes to the `kubescape.io` website repository. - `.github/workflows/create-release.yaml`: The workflow has been updated to execute the documentation generator script with every release. - `.github/sync.yml`: This new file specifies the source and destination directories for the synchronization process. It indicates that the `docs/controls` directory should be synced to the `docs/docs/controls/` directory in the `kubescape/kubescape.io` repository.

User Description:

Overview

As part of the LFX mentorship, creating a documentation pipeline to automatically generate and update the controls library documentation.

Adding a script to generate markdown files as documentation for each control in controls folder, a index.md file and stores them in the directory docs/controls.
Adding the script to the release workflow, so the script will run automatically with every release.
Adding a sync.yml action which is triggered automatically upon any changes to docs/controls directory. The action opens a pull request syncing only the changes to kubescape.io website repository.

[x] My code follows the style guidelines of this project
[x] I have commented on my code, particularly in hard-to-understand areas
[x] I have performed a self-review of my code

PR Analysis

🎯 Main theme: Automated documentation generation and synchronization pipeline
📝 PR summary: This PR introduces an automated documentation generation and synchronization pipeline for the control library. It modifies the upload-readme.py script to generate static markdown files for each control, adds a new GitHub action that triggers on changes to the docs/controls directory, and updates the create-release.yaml workflow to execute the documentation generator script with every release. A new script mk-generator.py is also added to generate the markdown files.
📌 Type of PR: Enhancement
🧪 Relevant tests added: No
⏱️ Estimated effort to review [1-5]: 3, because the PR involves changes in multiple files and scripts, and introduces new functionality that needs to be thoroughly reviewed for potential issues.
🔒 Security concerns: No security concerns found

PR Feedback
💡 General suggestions: The PR is well-structured and the changes are logically grouped. The addition of an automated documentation generation and synchronization pipeline is a valuable enhancement. However, it would be beneficial to include some form of testing or validation to ensure the generated markdown files and the synchronization process are functioning as expected. Additionally, consider handling potential exceptions or errors that may occur during the execution of the scripts.
🤖 Code feedback:
- relevant file: scripts/upload-readme.py suggestion: Consider adding error handling and logging to the script. This can help in debugging issues if the script fails to run correctly. For example, in the authenticate method of the ReadmeApi class, if the status code is not 200, an exception is raised. It would be helpful to log the response or the error message before raising the exception. [important] relevant line: '+ raise Exception('Failed to authenticate')'
- relevant file: .github/workflows/sync.yml suggestion: It would be beneficial to add more details to the PR body in the Run GitHub File Sync step. This can include information about the changes made, the reason for the changes, and the expected impact. This can help reviewers understand the context and purpose of the PR. [medium] relevant line: '+ PR_BODY: Syncing the Control Library docs from regolibrary repository to update the controls documentation'
- relevant file: .github/workflows/create-release.yaml suggestion: Consider adding error handling or a fallback mechanism in the execute docs generator script step. If the script fails to execute, it could prevent the release workflow from completing. [important] relevant line: '+ run: python ./scripts/mk-generator.py'
- relevant file: scripts/upload-readme.py suggestion: Consider refactoring the create_md_for_control function. This function is quite long and does multiple things. Breaking it down into smaller, more manageable functions can improve readability and maintainability. [medium] relevant line: '+def create_md_for_control(control):'

How to use

Instructions

To invoke the PR-Agent, add a comment using one of the following commands: /review: Request a review of your Pull Request. /describe: Update the PR title and description based on the contents of the PR. /improve [--extended]: Suggest code improvements. Extended mode provides a higher quality feedback. /ask \<QUESTION>: Ask a question about the PR. /update_changelog: Update the changelog based on the PR's contents. /add_docs: Generate docstring for new components introduced in the PR. /generate_labels: Generate labels for the PR based on the PR's contents. see the tools guide for more details.

To edit any configuration parameter from the configuration.toml, add --config_path=new_value. For example: /review --pr_reviewer.extra_instructions="focus on the file: ..." To list the possible configuration parameters, add a /config comment.

kubescape / regolibrary