Automatically generate docs

[fmvilas]

Reason/Context

When describing the benefits of a spec-driven framework like Glee, I'm always mentioning the fact that we could have docs and code always in sync. However, we're not generating any docs, we're leaving this responsibility to the user, which kinda breaks the purpose 😅

Description

We should provide a way to automatically generate docs. Here are the ways that come to my mind:

1. Start an HTTP static server and serve the docs there. For instance, http://localhost:3000/docs would show the docs. Fully configurable from the glee.config.js file.
2. Generate docs in a folder inside the project. Fully configurable from glee.config.js file, like the path to the folder and the Generator template to use. We can default to docs and the https://github.com/asyncapi/markdown-template/.
3. A Github Action (maybe Gitlab CI too?) that calls a webhook URL (or multiple ones?) to update external systems, like developer portals. E.g., a POST call to a URL containing the AsyncAPI definition. This should be a separate package though.

[likitarai1]

I would like to create a GSoC proposal on this issue.

[AceTheCreator]

@fmvilas since GSOC rejected us this year, I guess I should just work on this issue. I need to get familiar with glee very well cuz I'll be using it as an example of one of the amazing tools the AsyncAPI community is building during my talk at Osca fest later this month.

[fmvilas]

Yeah go ahead mate 👍

[AceTheCreator]

Yo @fmvilas, now I have the time to start contributing to this project. LOL

Wanna confirm when you say docs, do you mean the AsyncAPI docs?

[fmvilas]

Yeah, leverage Generator to generate HTML or markdown docs.

[Sihamtahi]

Hi, I want to work on this issue for the mentorship program . I am working in my internship on the automatic generation of a formalism-b to java. I want to take the challenge with the AsyncAPI documentation too

[fmvilas]

Awesome, @Sihamtahi! @AceTheCreator did you start working on the issue already? If this issue gets selected for the Mentorship program and @Sihamtahi is selected as well, maybe you can mentor her. How does that sound? I hope it's not too late and you have the code running in your machine 😄

[AceTheCreator]

I've started working on it already and I think I'm almost done, I didn't know it's part of the mentorship program. @fmvilas what do I do? 😂 @Sihamtahi can you pick another issue and I'm willing to help you

[Sihamtahi]

Hello @fmvilas @AceTheCreator this is brilliant 😂😂. Yes, in fact, I have commented in other issues. So, if i was selected i will contact you.
Thank you 🙏

[fmvilas]

Perfect! I'm removing the gsoc label to avoid confusion.

[AceTheCreator]

Hey, @fmvilas any idea why I'm getting this error while trying to build the package?

[fmvilas]

Uh! 🤔 I have no idea. I'm not getting this error. Check the Typescript version just in case.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[fmvilas]

@AceTheCreator in the end, I also faced this issue and got a fix for it: #326.

[asyncapi-bot]

🎉 This issue has been resolved in version 0.13.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀