Add tutorial that explains step by step how to create a simple Generator Template

[derberg]

Reason/Context

So we already have https://www.asyncapi.com/docs/tools/generator/template-development that nicely explains all basic requirements for a template and possible features.

What we are missing is a tutorial that someone follows to:

• create a simple template
• without additional noise of explaining every feature - this can be mitigated by linking to other docs
• explanation of something in action, that reader can actually run at the end

This could be a foundation for further development of more tutorials that would basically add more features to this test template

Description

• it should follow the same for as other tutorials, like -> https://www.asyncapi.com/docs/tutorials/create-asyncapi-document
• it should be as simple to use as possible, so for example we do not explain how to create an AsyncAPI document, as in this tutorial it is just one of required assets that someone should already have so we just say if you do not have asyncapi document to test your template with, just run asyncapi new --example=tutorial.yml --no-tty to get one
• tutorial examples should be based on AsyncAPI document generated with asyncapi new --example=tutorial.yml --no-tty from AsyncAPI CLI
• we could have a super simple code generator as an example (https://medium.com/python-point/mqtt-basics-with-python-examples-7c758e605d4 Publish to a Topic). So the tutorial would explain all about code generation template, how to grab channel name and message info from AsyncAPI using Parser
• then we would have another section that would guide someone on how to test the template locally, how to run it and make sure it works

I'm happy to help with knowledge sharing session and initial development of the template that will serve as an example here

[pratik9315]

Makes sense👍 It's about time we add a separate tutorial that a reader can follow to create and run an example template

[thulieblack]

This issue is part of the AsyncAPI Bounty Program, interested contributors need to follow the guidelines below to ensure fairness and timely completion of assigned tasks:

Task Assignment

The assignment of tasks will be prioritized in the following order:

• AsyncAPI maintainers (from any repository)
• Regular contributors (individuals who have merged three or more pull requests)
• Other (if an individual doesn't fall under the above, the maintainer can determine the criteria i.e regular volunteers, etc)

We encouraged everyone to apply as long as the task is for you (falls under your skill set). We will not be using the first comment - get assigned method for assignments. Instead, we will provide 3 days to consider all individuals interested before assigning any bounty task.

Deadline

To maintain accountability and ensure the timely completion of the deadline for this task will be 6 - 8 weeks from the date of assignment. If a contributor requires an extension on their task, it should be communicated and approved by the maintainer.

Issue Tracking and Updates

Contributors must provide weekly updates on the task they are working on to help maintainers stay informed of progress. If a contributor fails to provide an update, they will be reminded via a ping. If a contributor fails to provide an update after three pings over three weeks, we will assume they have silently dropped the issue, and it will be reassigned to someone else.

Issue Drop-outs

Any contributor who drops an assigned issue will be penalized and will not be eligible to participate in the bounty program for 6 months. We understand that unforeseen circumstances can arise, and dropping an assigned issue may be unavoidable in some cases. However, we believe that enforcing this penalty is necessary to ensure the effectiveness of the bounty program, respect maintainer time, and honor the efforts of other contributors who could have solved the issue but were unable to do so due to the drop-out.

We encourage all contributors to follow these guidelines to ensure a fair and timely completion of tasks assigned through our bounty program.

[Florence-Njeri]

@derberg @thulieblack I'm interested in authoring the tutorial.

[octonawish-akcodes]

@derberg I am interested too in this

[derberg]

@Florence-Njeri has a priority to work on this issue as docs maintainer for generator. @octonawish-akcodes have a look on other bounty issues 🙏

@Florence-Njeri so 😃 when do we start 😃

[octonawish-akcodes]

@derberg Oops there arent any other bounty issues available

[derberg]

@octonawish-akcodes There are some -> https://github.com/issues?q=is%3Aopen+org%3Aasyncapi+label%3A%22bounty%22 or did you look for docs task only?

[Florence-Njeri]

@derberg 8th May will work well for me since I'm going on holiday next week.

[derberg]

@Florence-Njeri perfect, we have lots of holidays next week in Poland anyway 😃 Let's sync on slack for an onboarding call

[derberg]

just had an onboarding call with @Florence-Njeri to explain the scope and align how we work on it, especially that some technical input is needed first.

for now makes sense to keep tutorial under Tools -> Generator bucket and follow the same template as https://www.asyncapi.com/docs/tutorials/generate-code

but if during template development, we will figure it do not makes sense, we will change approach

[thulieblack]

Hey, @Florence-Njeri how's the task going?

[derberg]

for now Florence is blocked by my tech input that I work on "as we speak" 😃

[derberg]

@Florence-Njeri ok, so when I started working on technical input, I kinda started feeling the blues, you know and while making notes, I figured I can turn it into article.

I just opened PR to my blog https://github.com/derberg/derberg.github.io/pull/62 and you can preview it here https://derberg-github-io-git-articlecodegenpython-derberg.vercel.app/blog/asyncapi-codegen-python

it is work in progress, there are some technical issues

this doesn't mean the tutorial is not needed. On the contrary, it is super needed. Article is written from a personal note, as a story, so it can only be reused by you as technical input. Of course you do not have to explain parser, generator and other stuff like I did as your tutorial is part of the docs where these things are explained and you can link.

anyway, you can already start working on tutorial. The best way to write it is when you will replicate tutorial steps on your own.

ah, and one more note, article is in progress, I did not read it as a whole, there is a bunch of grammar mistakes so please don't laugh 😄

[thulieblack]

This blog, ehn, took the words right out of my mouth.

[Florence-Njeri]

@thulieblack @derberg I've started working on the tutorial, hoping to put up a PR before end of the week

[derberg]

ok, so article is now live: https://www.brainfart.dev/blog/asyncapi-codegen-python

sample template that I developed while writing the article is here: https://github.com/derberg/python-mqtt-client-template

enjoy 😄

[Florence-Njeri]

Hey guys @derberg @thulieblack, I've finished writing the first draft for the tutorial. I need to do an editorial check then I'll put up a PR for this issue.

[asyncapi-bot]

:tada: This issue has been resolved in version 1.10.11 :tada:

The release is available on:

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

Your semantic-release bot :package::rocket: