Feature: Automatic documentation generation from TSDoc comments and Improved Workflow

[Fritsch-Tech]

🔧 Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Codebase improvement
• Other (if none of the other choices apply)

🚨 Checklist

• I've read the guidelines for contributing
• I've added necessary documentation (if appropriate)
• I've ensured that my code additions do not fail linting or unit tests (if applicable)

Description

This pull request introduces automatic documentation generation using API-extractor and TSDoc. Additionally, the new documentation is linked in the README to provide easy access for users.

The following changes were made:

1. Automatic documentation Generation: With the integration of API-extractor, the project now automatically generates Documentation from TSDoc comments, improving code documentation and clarity.

2. Linked Documentation in README: The README has been updated to include a link to the newly generated TSDoc documentation, making it easily accessible to users.

3. Updated Commands: New commands have been created. All essential commands for the generation of the documentation (format, lint, test, and doc generation) have been combined into a single command named "prepare" to simplify the development workflow.

4. Updated CONTRIBUTING.md: The CONTRIBUTING.md file has been updated to reflect the changes in the workflow and provide instructions on using the "pre-pull-request" command.

Request for TSDoc Format

Before proceeding with further documentation, I'd like to confirm if it's okay to use TSDoc format for our documentation. Once I receive your approval, I'll start documenting the code accordingly.

Note on Current Documentation

As of now, the automatically generated documentation might not be as useful since the code requires proper commenting according to the TSDoc format. Before merging this pull request, I plan to complete the documentation for the existing codebase.

Questions

• For deploying and generating the documentation automatically, one option is to create a GitHub Actions workflow that triggers on push to the main branch. The workflow can run the necessary commands to generate the documentation and deploy it to a specified location.

• As for hosting the documentation, creating a separate gh-pages branch and deploying the documentation there is a common approach. By doing so, we can link the website in the README, making it easy for users to access the documentation. Alternatively we leave the documentation simple in the docs folder and link it in the README.

[gremo]

Ok, I'm supper happy with this PR I just want to split to better understand how it works and how could be improved. For example, I think it's not necessary to "build" docs manually, could be easily done with a workflow action + autocommit. I'll try to investigate further.

In the meanwhile, can we just add TSDoc everywhere in the source code? That is:

• Component documentation
• ESLint plugin

Leaving out all the stuff needed for the generation.

[Fritsch-Tech]

Yes, I would start to add the TSDoc comments to the code in the next couple of days.
Idealy we would then have a Seperate PR just for all the TSDoc comments and the ESLint plugin and focus this one only on the generation of the Documentation of them.

I would propose we add the docs folder to the .gitinore and make a workflow action that triggers on pushes to the main branch. This workflow would then make a cleanup, generate the docs and force pushes them to main.

Then we could activate gh-pages on the main branch and point it to the docs folder. This would look like this: Docs Demo

Thanks for taking your time reviewing all my PR's. I realy appreciated it.

[Fritsch-Tech]

I have now implemented a proper GitHub workflow. To ensure everything functions smoothly, the GitHub action requires write permissions to the repository. Additionally, once the documentation is generated, you can enable GitHub Pages on the main branch specifically for the ´docs´ directory. This will result in a polished and comprehensive documentation website.